-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #5 from FoskyM/docs
docs
- Loading branch information
Showing
3 changed files
with
183 additions
and
25 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,90 @@ | ||
| ### setting | ||
|  | ||
|
|
||
| - `Allow Implicit Grant` a way to return token directly to client, you can google it | ||
| - `Enforce State Validation` `state` must be provided | ||
| - `Require Exact Redirect URI` url in `redirect_uri` should be exactly the same as the one of client | ||
| - `Access Token Lifetime` | ||
|
|
||
| ### create a client | ||
|  | ||
| #### instructions | ||
| - `Name` name of client | ||
| - `Description` description of client | ||
| - `Icon` icon of client, optional | ||
| - `Homepage` homepage of client, optional | ||
| - `Redirect URI` redirect uri of client, required, multiple uri should be separated by space (not recommended) | ||
| - `Scopes` optional (don't fill it if you don't know) | ||
| - `Grant Types` optional (don't fill it if you don't know) | ||
| - `Client ID` and `Client Secret` used for client authentication, generated automatically, don't share it with others | ||
|
|
||
| ### set scope for your resources (user.read is default scope) | ||
|  | ||
| most people only need `user.read` scope, if you need more, you can add it here (maybe you need to know something about OAuth scope first) | ||
| #### instructions | ||
| - `Scope ID` unique identifier of scope, used for distinguish, you can refer to `Github` scope | ||
| - `Resource Path` resource path of scope | ||
| - `Request Method` request method of resource path, usually `GET` | ||
| - `Default` if checked, this scope will be added even if it's not in `scope` parameter | ||
| - `Name` name of scope, used for display | ||
| - `Description` description of scope, used for display, you can use `{user}` `{client_name}` variable to represent user and client name | ||
| - `Icon` support `FontAwesome` icon and normal image | ||
|
|
||
| ### uri | ||
| #### authorize | ||
| `/oauth/authorize` | ||
|
|
||
| | param | description | required | default | example | | ||
| | --- | --- | --- | --- | --- | | ||
| | client_id | client id | yes | none | 123456 | | ||
| | response_type | grant type | yes | none | code or token | | ||
| | redirect_uri | redirect uri | yes | client redirect uri | https://example.com/oauth/callback | | ||
| | scope | scope | no | none | user.read | | ||
| | state | state | no | none | 123456 | | ||
|
|
||
| example： | ||
| ``` | ||
| GET https://example.com/oauth/authorize?client_id=123456&response_type=code&redirect_uri=https://user.example.com/oauth/callback&scope=user.read&state=123456 | ||
| ``` | ||
|
|
||
| #### token | ||
| `/oauth/token` | ||
|
|
||
| | param | description | required | default | example | | ||
| | --- | --- | --- | --- | --- | | ||
| | client_id | client id | yes | none | 123456 | | ||
| | client_secret | client secret | yes | none | 123456 | | ||
| | grant_type | grant type | yes | none | authorization_code or refresh_token | | ||
| | code | authorization code | required when grant type is authorization_code | none | 123456 | | ||
| | refresh_token | refresh token | required when grant type is refresh_token | none | 123456 | | ||
| | redirect_uri | redirect uri | required when grant type is authorization_code | client redirect uri | https://example.com/oauth/callback | | ||
|
|
||
| example： | ||
| ``` | ||
| POST https://example.com/oauth/token | ||
| Payload: client_id=123456&client_secret=123456&grant_type=authorization_code&code=123456&redirect_uri=https://example.com/oauth/callback | ||
| ``` | ||
|
|
||
| ### resource | ||
| `/api/user` | ||
|
|
||
| | param | description | required | default | example | | ||
| | --- |--------------|-----|---------| --- | | ||
| | access_token | access token | yes | none | 123456 | | ||
|
|
||
| ### example | ||
|
|
||
| ``` | ||
| GET https://example.com/api/user?access_token=123456 | ||
| ``` | ||
|
|
||
| ### do it as normal OAuth client | ||
|  | ||
|
|
||
| ### get access token after authorized | ||
|  | ||
|
|
||
| ### using token to access resources (get or header) | ||
|  | ||
|  |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,91 @@ | ||
| ### 配置项 | ||
|  | ||
| #### 配置项说明 | ||
| - `允许隐式授权` response_type=token 的方式，令牌直接通过 hash 返回给客户端，详细说明可百度 | ||
| - `强制状态验证` state 参数必须存在 | ||
| - `精确的重定向 URI` 传参时的重定向 URI 必须和创建应用时填写的一致 | ||
| - `令牌有效期` 令牌的有效期，单位为秒 | ||
|
|
||
| ### 创建应用 | ||
|  | ||
| #### 应用创建说明 | ||
| - `应用名称` 应用的名称 | ||
| - `应用描述` 应用的描述 | ||
| - `应用图标` 应用的图标，可选 | ||
| - `应用主页` 应用的主页，可选 | ||
| - `应用回调地址` 应用的回调地址，必填，多个地址使用空格分隔（不推荐单个应用使用多个地址） | ||
| - `权限` 可选（不清楚的话不要填） | ||
| - `授权类型` 可选（不清楚的话不要填） | ||
| - `应用 ID` 和 `应用密钥` 用于客户端认证，添加应用时自动生成，不要泄露给其他人 | ||
|
|
||
| ### 设置资源控制器的权限 (user.read 项是默认生成的权限) | ||
|  | ||
| 大部分人只需要 `user.read` 权限即可，如果你需要更多的权限，可以在这里添加（或许你需要先了解一下 OAuth 中的 scope） | ||
| #### 权限说明 | ||
| - `权限标识` 权限唯一标识符，用于区分，可参考 `Github` 的权限标识 | ||
| - `资源路径` 需要鉴权的资源路径 | ||
| - `请求方法` 资源路径鉴权的请求方法，一般为 `GET` | ||
| - `默认` 勾选此项后哪怕传参时 scope 参数中无此权限标识，也会默认添加此权限 | ||
| - `名称` 权限的名称，用于显示 | ||
| - `描述` 权限的描述，用于显示，可使用 `{user}` `{client_name}` 变量指代用户和客户端名称 | ||
| - `图标` 支持 `FontAwesome` 图标和普通图片 | ||
|
|
||
| ### 本插件相关路径 | ||
| #### 授权 | ||
| `/oauth/authorize` | ||
|
|
||
| | 参数 | 说明 | 必填 | 默认值 | 示例 | | ||
| | --- | --- | --- | --- | --- | | ||
| | client_id | 应用 ID | 是 | 无 | 123456 | | ||
| | response_type | 授权类型 | 是 | 无 | code 或 token | | ||
| | redirect_uri | 重定向 URI | 是 | 应用回调地址 | https://example.com/oauth/callback | | ||
| | scope | 权限 | 否 | 无 | user.read | | ||
| | state | 状态 | 否 | 无 | 123456 | | ||
|
|
||
| 示例： | ||
| ``` | ||
| GET https://example.com/oauth/authorize?client_id=123456&response_type=code&redirect_uri=https://user.example.com/oauth/callback&scope=user.read&state=123456 | ||
| ``` | ||
|
|
||
| #### 令牌 | ||
| `/oauth/token` | ||
|
|
||
| | 参数 | 说明 | 必填 | 默认值 | 示例 | | ||
| | --- | --- | --- | --- | --- | | ||
| | client_id | 应用 ID | 是 | 无 | 123456 | | ||
| | client_secret | 应用密钥 | 是 | 无 | 123456 | | ||
| | grant_type | 授权类型 | 是 | 无 | authorization_code 或 refresh_token | | ||
| | code | 授权码 | 授权类型为 authorization_code 时必填 | 无 | 123456 | | ||
| | refresh_token | 刷新令牌 | 授权类型为 refresh_token 时必填 | 无 | 123456 | | ||
| | redirect_uri | 重定向 URI | 授权类型为 authorization_code 时必填 | 应用回调地址 | https://example.com/oauth/callback | | ||
|
|
||
| 示例： | ||
|
|
||
| ``` | ||
| POST https://example.com/oauth/token | ||
| Payload: client_id=123456&client_secret=123456&grant_type=authorization_code&code=123456&redirect_uri=https://example.com/oauth/callback | ||
| ``` | ||
|
|
||
| #### 资源(用户) | ||
| `/api/user` | ||
|
|
||
| | 参数 | 说明 | 必填 | 默认值 | 示例 | | ||
| | --- | --- | --- | --- | --- | | ||
| | access_token | 访问令牌 | 是 | 无 | 123456 | | ||
|
|
||
| 示例： | ||
|
|
||
| ``` | ||
| GET https://example.com/api/user?access_token=123456 | ||
| ``` | ||
|
|
||
| ### 和常规的 OAuth 应用一样使用 | ||
|  | ||
|
|
||
| ### 授权后获取令牌 | ||
|  | ||
|
|
||
| ### 使用令牌获取资源 (使用 get 或 header 方式) | ||
|  | ||
|  |