docs
This commit is contained in:
FoskyM
parent
dcc195aca9
commit
815eb314a6
3 changed files with 183 additions and 25 deletions
27
README.md
27
README.md
|
|
@ -22,31 +22,8 @@ php flarum cache:clear
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
### setting
|
- [中文文档](/docs/zh.md)
|
||||||
|
- [English Docs](/docs/en.md)
|
||||||
|
|
||||||
### create a client
|
|
||||||
|
|
||||||
|
|
||||||
### set scope for your resources (user.read is default scope)
|
|
||||||
|
|
||||||
|
|
||||||
### uri
|
|
||||||
authorize: `/oauth/authorize`
|
|
||||||
|
|
||||||
token: `/oauth/token`
|
|
||||||
|
|
||||||
resource(user): `/api/user`
|
|
||||||
|
|
||||||
### do it as normal OAuth client
|
|
||||||
|
|
||||||
|
|
||||||
### get access token after authorized
|
|
||||||
|
|
||||||
|
|
||||||
### using token to access resources (get or header)
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## Links
|
## Links
|
||||||
|
|
||||||
|
|
|
||||||
90
docs/en.md
Normal file
90
docs/en.md
Normal file
|
|
@ -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)
|
||||||
|
|
||||||
|
|
||||||
91
docs/zh.md
Normal file
91
docs/zh.md
Normal file
|
|
@ -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 方式)
|
||||||
|
|
||||||
|
|
||||||
Loading…
Reference in a new issue