# 认证与授权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。
注意
scope_data
字段需要进行URL编码- 如果你是智能硬件设备,你需要在设备接入控制台 (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
用户打开以上链接后,首先需要进行登录(无需注册,使用手机验证码进行登录),登录成功后,会出现类似以下【确认授权】的页面:
提醒
- 用户可以选择 授权 或者 拒绝
- 测试调试阶段,请在设备接入控制台 (opens new window)的
设备测试
页添加手机号白名单,否则将会造成授权失败。
# 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
整体授权流程:
# 使用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"
}