授权 OAuth 应用

当前位置鱼摆摆网 > 教程 > 自媒体 >

作者：肖钦 2019-10-24 16:11

语雀支持标准的OAuth2 authorization code授权模式

Web 应用流程

流程

用户被重定向以请求他们的语雀身份

用户被语雀重定向回你的网站

你的应用使用用户的 access token 访问 API

时序图

1. 将用户重定向到语雀授权页

参数

用户确认授权后，将被重定向到应用指定的回调地址，并附带state和code参数。

2. 用户被重定向回应用回调地址

参数

3. 通过 code 换取用户 token

参数

响应

响应是一个 JSON 格式的字符串，包含用户授权后的 token，该 token 只能访问用户授权范围内的 API。

4. 通过 token 来访问语雀的 API

非 Web 应用流程

有些应用可能并没有服务端支持，而是一个纯客户端应用（浏览器插件、命令行工具），为了便于这类应用的授权，语雀提供了一种非 Web 应用的授权流程。

注意：此流程需要将client_secret下发到客户端中，有一定秘钥泄露的风险。

流程

客户端随机生成一个 40 位长度的 code。

将用户重定向到语雀的授权页，参数用 client_secret 加签。

用户确定授权，应用通过 code 调用语雀接口换取用户的 token。

通过 token 访问语雀开放 API。

1. 客户端生成 code

客户端自行生成一个长度为 40 的随机字符串（字母和数字组成），后续流程中需要用到。

2. 将用户重定向到语雀授权页

参数

所有的参数以字母顺序排序（client_id,code,response_type,scope,timestamp），将所有的参数值 URL encode，最后用&拼接到一起：需要对参数签名语雀才会认为是合法的应用发起的授权请求，签名方式如下：

client_id=IDg4dfUS5vaNo05vqrXa&code=2Omo46aDfdssxjpffffptMAbmuj7xu8dBURRsHun&response_type=code&scope=doc%2Crepo×tamp=1530243304828

将拼接好的字符串，使用 sha1 加签，秘钥为 client_secret，并对加签后的结果进行 base64 编码拿到字符串，设置到 sign 参数即可。

3.通过 code 调用语雀接口换取用户的 token

这个流程用户授权完成之后，不会再把 code 通过 URL 返回，客户端可以直接通过第一步中随机生成的 code 原始值调用语雀的接口换取用户的 token，这一步不需要再传递 client_secret。

参数

响应

响应是一个 JSON 格式的字符串，包含用户授权后的 token，该 token 只能访问用户授权范围内的 API。

一般来说，由于用户确认授权后不会回调，所以在将用户重定向到语雀授权页之后就可以开始轮询语雀的授权接口了（请注意轮询间隔时长控制在 3s 左右）。

4. 通过 Token 来访问语雀的 API

后续流程和 OAuth 授权一样，通过 token 即可以授权用户的身份访问 API。

Node.js 客户端

Node.js 版本的授权过程已经封装成了一个模块yuque-auth，如果应用是 Node.js 编写，可以直接使用，其他语言也可以参考该模块自行实现。

常见的接口错误

请求参数错误

此错误只在 “非 Web 应用流程”（即在参数中传）中出现

错误接口：POST /oauth2/authorize

错误原因：

sign 传了空字符串

sign 不合法（参数以字母顺序排序（ client_id , code , response_type , scope , timestamp ），将所有的参数值 URL encode，最后用 & 拼接到一起，将拼接好的字符串，使用 sha1 加签，秘钥为 client_secret，并对加签后的结果进行 base64 编码拿到字符串）

timestamp 传了空字符串

timestamp 不在现在时间的正负 10 分钟之内

code 长度不是 40 个字符

client_id 不正确

authorization code is invalid

错误接口：POST /oauth2/token

错误原因：

code 传了空字符串

client_id 传了空字符串

client_id 传了不是自己应用的 client id

grant_type 传了不匹配的值

authorization client is invalid