授权 OAuth 应用

语雀全力支持国际标准的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

错误接口：POST /oauth2/token

错误原因：

应用领域已经删除

grant_type invalid

错误接口：POST /oauth2/token

错误原因：

模块grant_type 不是authorization_code 或 client_code

版权声明：本文内容由互联网采用者自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如发现本站有涉嫌抄袭侵权/违法违规的内容， 请发送邮件至 yubaibai360@qq.com 举报，一经查实，本站将立刻删除。