# 授权接入

# 简介

我们通过合作方提供的OAuth2.0授权服务，使iFLYOS的用户与合作方的用户进行授权绑定。这样iFLYOS就可以在不获取合作方用户账号密码的情况下，查询操作用户授权的设备。

TIP

OAuth2.0开放授权协议 (opens new window)

# 授权绑定流程

授权流程如下：
授权流程说明
- iFLYOS为用户提供带有临时信息（state）的授权链接
- 用户访问上一步获取的链接（合作方平台的授权链接）
- 合作方确认用户授权，将用户页面重定向到iFLYOS的回调页面（ https://iot.iflyos.cn/oauth/callback ）
- iFLYOS通过上一步返回的授权code，向合作方请求用户Token信息
- iFLYOS获取到Token信息后，返回成功页面
合作方需要提供的信息
- iFLYOS请求申请授权、获取 Token 信息时，需要用到的Client ID 与 Client Secret
- 授权服务提供的申请授权的地址（比如：https://xxx.cn/oauth/authorize ）
- 授权服务提供的获取Token信息的地址（比如：https://xxx.cn/oauth/token ）
- 用于设备发现、操作、查询的URL（比如：https://xxx.cn/v1/api ）
iFLYOS的回调地址：https://iot.iflyos.cn/oauth/callback
合作方需要实现的授权接口信息如下
- 申请授权接口（即用户打开的链接）
```
https://example.com/auth/authorize?client_id=xxxxxxxxx&redirect_uri=https%3A%2F%2Fiot.iflyos.cn%2Foauth%2Fcallback&response_type=code&state=xxxxxxxxx
```
  参数说明：
  - client_id : 合作方提供的 Client ID
  - redirect_uri : iFLYOS的回调地址，这个参数会进行UrlEncode，合作方在授权后，将用户页面重定向到该页面
  - response_type : 固定值，code
  - state : 由iFLYOS生成的临时信息，可以是任意字符串，合作方重定向页面时，在url参数中返回
  TIP
  
  上述链接中的 https://example.com/auth/authorize 即是合作方提供的 申请授权的URL
- 获取用户Token信息接口
```
https://example.com/auth/token?grant_type=authorization_code&client_id=xxxxxxxxx&client_secret=xxxxxxxxx&code=xxxxxxxxx&redirect_uri=https%3A%2F%2Fiot.iflyos.cn%2Foauth%2Fcallback
```
  参数说明：
  - grant_type : 固定值，authorization_code
  - client_id : 合作方提供的 Client ID
  - client_secret : 合作方提供的 Client Secret
  - code : 用户确认授权后，由合作方授权服务生成，重定向时通过url参数返回
  - redirect_uri : iFLYOS的回调地址，这个参数会进行UrlEncode
  TIP
  
  上述链接中的 https://example.com/auth/token 即是合作方提供的 获取Token信息地址
  
  正确响应：
```
{
    "access_token": "xxxx",
    "refresh_token": "xxxx",
    "expires_in": 86400000
}
```
  参数说明：
  
  参数类型说明
  
  access_token String 访问设备API时使用的令牌
  
  refresh_token String 用于刷新access_token的令牌
  
  expires_in long access_token的过期时长（单位：秒）
  
  TIP
  
  expires_in 请设置1天以上，建议3～4天
  
  错误响应：
  
  TIP
  
  当获取access_token发生错误时，http status code请勿返回200，可返回401、400、500（分别为：没有权限、参数错误、服务器内部错误）
```
{
    "error": "xxxx",
    "message": "xxxx"
}
```
  参数说明：
  
  参数类型说明
  
  error String 错误码
  
  message String 错误信息
- 刷新用户Token信息
```
https://example.com/auth/token?grant_type=refresh_token&client_id=xxxxxxxxx&client_secret=xxxxxxxxx&refresh_token=xxxxxxx
```
  参数说明：
  - grant_type : 固定值refresh_token
  - client_id : 合作方提供的 Client ID
  - client_secret : 合作方提供的 Client Secret
  - refresh_toekn : 获取Token信息时，返回来的refresh_token
  注意
  - 上述链接中的https://example.com/auth/token即是合作方提供的 获取Token信息地址
  - 响应结果与获取Token信息接口一致

参数	类型	说明
access_token	String	访问设备API时使用的令牌
refresh_token	String	用于刷新`access_token`的令牌
expires_in	long	`access_token`的过期时长（单位：秒）