OAuth2账户接入

版本：v1.0，更新时间：2019/10/1

接入说明

本文档描述了第三方独立应用系统如何通过OAuth2协议与得力E+平台完成用户账户的对接。

准备工作

应用接入方在正式接入前，需要向得力开放平台申请client_id和client_secret作为身份的标识。申请时需要提供以下信息：

接入地址

请使用以上域名替换接口定义中的DOMAIN信息完成对接。

用户授权

用户授权采用授权码模式进行登陆，接入方需要准备授权成功后的回调地址用来接受授权结果。

请求授权

接入方需要请求用户授权时，需要访问如下地址：

https://{DOMAIN}/oauth/authorize?response_type=code&client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&scope=read

各参数说明如下表格

参数名 参数说明 示例 备注
response_type 表示要求返回授权码，值只能使用code code
client_id 请求方的client_id，用来标识请求方的身份 353495291889643521
redirect_uri 请求方获得授权后的回调地址，用来返回授权结果 http://d.cn/callback
scope 要求的授权范围，默认为只读（read） read

用户授权

在https://{DOMAIN}/oauth/authorize页面，会要求用户登录，并要求用户对请求方的授权请求进行确认。

响应授权结果

在https://{DOMAIN}/oauth/authorize页面中，当用户对确认对请求方授权以后，页面会重定向到请求方提供的redirect_uri地址，并带上code参数。示例如下：

http://d.cn/callback?code={AUTHORIZATION_CODE}

各参数说明如下表格

参数名 参数说明 示例 备注
code 当前授权请求通过后获得的授权码 EjOEM0N1FBO6

请求方使用授权码

当页面重定向到http://d.cn/callback?code={AUTHORIZATION_CODE}时，请求方的后端应该使用授权码向得力开发平台请求令牌。

请求令牌的访问地址如下：

https://{DOMAIN}/oauth/token?client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}&grant_type=authorization_code&code={AUTHORIZATION_CODE}
各参数说明如下表格

参数名 参数说明 示例 备注
client_id 请求方的client_id，用来标识请求方的身份 353495291889643521
client_secret 请求方的client_secret，用来标识请求方的身份 kQIE3OCQu6oO6rfI
grant_type 授权方式，此时只能使用authorization_code authorization_code
code 授权码，响应授权结果的重定向回调中获得的code参数 EjOEM0N1FBO6

获得令牌

得力开放平台接受到请求令牌的请求后，会校验请求数据是否正确。请求数据正确的前提下，会向请求做出响应，发放令牌。

响应的数据内容如下：

 {
   "access_token": "{ACCESS_TOKEN}",
   "token_type": "bearer",
   "refresh_token": "{REFRESH_TIME}",
   "expires_in": 3600,
   "scope": "read"
}
各参数说明如下表格

参数名 参数说明 示例 备注
access_token 请求方的可以使用的访问令牌 73584115-2ae7-463c-bda1-c69ab159e97c
token_type 令牌的类型，有bearer和mac两种，默认是bearer bearer
expires_in 令牌过期时间（秒） 3600
refresh_token 当访问令牌过期时使用的刷新令牌 9870e744-5b71-4df6-9fe6-7fae4eaf583c
scope 获取授权的范围 read

令牌的使用

请求方拿到令牌以后，就可以调用得力开放平台的 API 请求资源数据。

每个发到 API 的请求，都必须带有令牌。一种做法是在请求的头信息，加上一个Authorization字段，令牌就放在这个字段里面。

curl -H "Authorization: Bearer ACCESS_TOKEN" https://{DOMAIN}/api/getUserInfo

上面命令中，ACCESS_TOKEN就是拿到的令牌。

另外一种做法是直接在请求参数中传递access_token：

curl -X GET https://{DOMAIN}/api/getUserInfo?access_token={ACCESS_TOKEN}

更新令牌

在令牌到期之前，请求方需要提前更新令牌。

刷新令牌的访问地址如下：

https://{DOMAIN}/oauth/token?grant_type=refresh_token&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}&refresh_token={REFRESH_TOKEN}
各参数说明如下表格

参数名 参数说明 示例 备注
client_id 请求方的client_id，用来标识请求方的身份 353495291889643521
client_secret 请求方的client_secret，用来标识请求方的身份 kQIE3OCQu6oO6rfI
grant_type 授权方式，此时只能使用refresh_token refresh_token
refresh_token 刷新令牌，用来刷新令牌的令牌 9870e744-5b71-4df6-9fe6-7fae4eaf583c

刷新成功后，会响应新的令牌信息。

 {    
   "access_token":"ACCESS_TOKEN",
   "token_type":"bearer",
   "expires_in":2592000,
   "refresh_token":"REFRESH_TOKEN",
   "scope":"read"
 }
数据结构与初次获取令牌时一致。每次调用请求都会刷新access_token, 但refresh_token不会变。

获取用户数据

此接口用于获取当前授权用户的个人信息。

请求说明

curl -X GET https://{DOMAIN}/api/getUserInfo?access_token=73584115-2ae7-463c-bda1-c69ab159e97c

返回说明

正确的Json返回结果：

{
   "openid": "45163500c88c8244499f0e571672db5f",
   "name": "19999000000",
   "headimgurl": "http://file.delicloud.com/oss-1517989949070-315.png"
}
参数 说明
openid 普通用户的标识，对当前开发者帐号唯一
name 普通用户姓名
headimgurl 用户头像，用户没有头像时该项为空

错误处理

如果API调用出现授权错误，会返回具体的错误消息，格式如下：

{
   "error": "{ERROR}",
   "error_description": "{ERROR_DESCRIPTION}"
}

各参数说明如下表格

参数名 说明 示例 备注
error 错误字符串 invalid_grant
error_description 错误具体描述 invalid code: nvMrfqnGeOx7