# 认证与授权API

# 用户与设备

用户是指购买厂商产品设备的消费者,是iFLYOS的用户,也是厂商的用户

设备是指厂商在设备接入平台 (opens new window)创建了设备后,将 Client ID 与自家的产品进行绑定,最终到达消费者手里的智能语音设备

# 为什么需要认证授权

通过 EVS协议IVS协议 使用接入语音服务时,iFLYOS需要确认发起请求的是哪个用户通过哪个设备来请求的,有了这两个信息,我们可以更好的为返回更适合用户的指令,更好的帮助用户得到他们想要的答案、完成他们想要完成的事情。

# 如何认证授权

iFLYOS专门为设备提供了一套简易安全的授权流程,使得用户可以快速的授权设备。

如果厂商不方便接入iFLYOS账号,则需要使用第三方账号来接入iFLYOS。这种情况下,对于用户认证、设备授权的安全性,更多的由厂商的服务提供保证。点击查看第三方账号认证授权

# STEP1:设备申请授权

设备向iFLYOS的授权服务发起一个POST请求,表明需要授权:

请求地址: https://auth.iflyos.cn/oauth/ivs/device_code

请求必须包含以下参数:

  • client_id: 在设备接入平台 (opens new window)的设备信息里查看
  • scope: 固定值user_ivs_all
  • scope_data: 包含设备信息的 JSON,包含device_id字段
    • device_id: 设备的唯一标识,建议使用设备SN作为device_id。

注意

  1. scope_data字段需要进行URL编码
  2. 如果你是智能硬件设备,你需要在设备接入控制台 (opens new window)设备ID页导入device_id列表,列表之外的device_id将会鉴权不通过。
{
    "user_ivs_all": {
        "device_id": "your device_id"
    }
}

curl示例:

curl -X POST \
  https://auth.iflyos.cn/oauth/ivs/device_code \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'client_id={{client_id}}&scope=user_ivs_all&scope_data=%7B%22user_ivs_all%22%3A%20%7B%22device_id%22%3A%20%20%2212345%22%7D%7D'

返回数据:

{
    "verification_uri": "https://auth.iflyos.cn/oauth/device",
    "user_code": "W6EBOU",
    "interval": 5,
    "expires_in": 600,
    "device_code": "0w21Wk2_FTnKmCyV1TqbiwauUrJjr9UiosIE-8Ka7f7zi5hCtv9zxEymGjNaXI9h"
}
参数 类型 说明
verification_uri String 用户校验用户授权码的链接地址
user_code String 简短的用户授权码
interval Integer 请求时间间隔
expires_in Integer 用户授权码有效时间,单位为秒
device_code String 设备授权码

# STEP2:用户授权

# 2.1

设备通过STEP 1的请求,(通过某种方式)将授权链接用户授权码组装发送到用户端,

让用户访问最终链接:

{{verification_uri}}?user_code={{user_code}}

例如: https://auth.iflyos.cn/oauth/device?user_code=W6EBOU

# 2.2

用户打开以上链接后,首先需要进行登录(无需注册,使用手机验证码进行登录),登录成功后,会出现类似以下【确认授权】的页面:

提醒

  1. 用户可以选择 授权 或者 拒绝
  2. 测试调试阶段,请在设备接入控制台 (opens new window)设备测试页添加手机号白名单,否则将会造成授权失败。

scopes

# STEP3:设备获取 AccessToken

注意

该步骤与Step 2是同步进行的

设备通过STEP 1的请求,获取到设备授权码,使用该授权码,轮循调用授权服务的接口,检测授权状态并获取AccessToken:

POST /oauth/ivs/token HTTP/1.1
Host: auth.iflyos.cn
Content-Type: application/json

{
	"client_id": "YOUR_CLIENT_ID",
	"grant_type": "urn:ietf:params:oauth:grant-type:device_code",
	"device_code": "YOUR_DEVICE_CODE"
}

curl示例:

curl -X POST \
  https://auth.iflyos.cn/oauth/ivs/token \
  -H 'content-type: application/json' \
  -d '{
	"client_id": "8d3d13ab-aea8-4595-ac4f-dda3f524450c",
	"grant_type": "urn:ietf:params:oauth:grant-type:device_code",
	"device_code": "8JyTH0Jm3yg_SavmvJ4WzGWgjnNlRNu2jV0oq--6nZW0OImk2jBEXdMeYpQuEkie"
}'

返回数据可能是:

  • 用户未授权,等待下一次轮循请求
{
    "error": "authorization_pending"
}
  • 授权码过期,用户仍未授权
{
    "error": "expired_token"
}
  • 用户拒绝授权
{
    "error": "access_denied"
}
  • 用户通过授权
{
    "token_type": "bearer",
    "refresh_token": "4_vujpFOfu0G5yf4**************DwX5S80s74CY7",
    "expires_in": 86400000,
    "created_at": 1526485197,
    "access_token": "bd6XMEqzIokI6mnMM**************iKAdYNa9T-1WXY"
}
参数 类型 说明
token_type String 固定值,bearer
access_token String 接入iFLYOS的令牌
refresh_token String 用于刷新AccessToken的令牌
expires_in long AccessToken的有效时长,单位为秒
created_at long 令牌创建时间

# 授权完成

至此,用户授权流程完成,这是一个标准的OAuth2设备授权流程,具体协议可以参考:https://oauth.net/2/grant-types/device-code

整体授权流程:

auth

# 使用refresh_token获取新的AccessToken

当AccessToken失效时,可以使用通过授权后获取到的refresh_token来获取新的AccessToken,同时返回的refresh_token可用于下次刷新。

POST /oauth/ivs/token HTTP/1.1
Host: auth.iflyos.cn
Content-Type: application/json

{
	"grant_type": "refresh_token",
	"refresh_token": "_NS6qnBUdJep*******************4ZZmBSP4Pbfy-jav4n3EiX"
}

curl示例:

curl -X POST \
  https://auth.iflyos.cn/oauth/ivs/token \
  -H 'content-type: application/json' \
  -d '{
	"grant_type": "refresh_token",
	"refresh_token": "_NS6qnBUdJep*******************4ZZmBSP4Pbfy-jav4n3EiX"
}'

返回数据可能是:

  • refresh_token无效
{
    "message": "refresh token错误",
    "error": "invalid_refresh_token"
}
  • 刷新token成功
{
    "token_type": "bearer",
    "refresh_token": "4_vujpFOfu0G5yf4**************DwX5S80s74CY7",
    "expires_in": 86400000,
    "created_at": 1526485197,
    "access_token": "bd6XMEqzIokI6mnMM**************iKAdYNa9T-1WXY"
}