From 815eb314a6996a94e3331c91d9fe6b1ef95fd3be Mon Sep 17 00:00:00 2001 From: FoskyM Date: Sat, 2 Dec 2023 10:57:23 +0800 Subject: [PATCH] docs --- README.md | 27 ++-------------- docs/en.md | 90 +++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/zh.md | 91 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 183 insertions(+), 25 deletions(-) create mode 100644 docs/en.md create mode 100644 docs/zh.md diff --git a/README.md b/README.md index c07dc02..1eaf423 100644 --- a/README.md +++ b/README.md @@ -22,31 +22,8 @@ php flarum cache:clear ## Usage -### setting -![Snipaste_2023-10-02_06-15-33](https://github.com/FoskyM/flarum-oauth-center/assets/39661663/0e8352bf-0aeb-4605-bd84-aaedf8cae0e8) - -### create a client -![Snipaste_2023-10-02_06-15-52](https://github.com/FoskyM/flarum-oauth-center/assets/39661663/e9879852-f4ec-4a04-9f81-58004692493c) - -### set scope for your resources (user.read is default scope) -![Snipaste_2023-10-02_06-16-06](https://github.com/FoskyM/flarum-oauth-center/assets/39661663/31648ad2-4326-47e0-9d26-c0e3b2f30f8d) - -### uri -authorize: `/oauth/authorize` - -token: `/oauth/token` - -resource(user): `/api/user` - -### do it as normal OAuth client -![Snipaste_2023-10-02_06-16-31](https://github.com/FoskyM/flarum-oauth-center/assets/39661663/1632672e-e631-41bc-b794-40428157b41c) - -### get access token after authorized -![Snipaste_2023-10-02_06-17-00](https://github.com/FoskyM/flarum-oauth-center/assets/39661663/52f1b984-345b-4e09-8b8c-dcdf39712fb3) - -### using token to access resources (get or header) -![Snipaste_2023-10-02_06-17-29](https://github.com/FoskyM/flarum-oauth-center/assets/39661663/aa79ad3b-a480-4d09-9159-359be4518f4b) -![Snipaste_2023-10-02_06-17-42](https://github.com/FoskyM/flarum-oauth-center/assets/39661663/5054ac5b-da79-4db3-9703-94e10a1cde5f) +- [中文文档](/docs/zh.md) +- [English Docs](/docs/en.md) ## Links diff --git a/docs/en.md b/docs/en.md new file mode 100644 index 0000000..1dcdae2 --- /dev/null +++ b/docs/en.md @@ -0,0 +1,90 @@ +### setting +![Snipaste_2023-10-02_06-15-33](https://github.com/FoskyM/flarum-oauth-center/assets/39661663/0e8352bf-0aeb-4605-bd84-aaedf8cae0e8) + +- `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 +![Snipaste_2023-10-02_06-15-52](https://github.com/FoskyM/flarum-oauth-center/assets/39661663/e9879852-f4ec-4a04-9f81-58004692493c) +#### 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) +![Snipaste_2023-10-02_06-16-06](https://github.com/FoskyM/flarum-oauth-center/assets/39661663/31648ad2-4326-47e0-9d26-c0e3b2f30f8d) +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 +![Snipaste_2023-10-02_06-16-31](https://github.com/FoskyM/flarum-oauth-center/assets/39661663/1632672e-e631-41bc-b794-40428157b41c) + +### get access token after authorized +![Snipaste_2023-10-02_06-17-00](https://github.com/FoskyM/flarum-oauth-center/assets/39661663/52f1b984-345b-4e09-8b8c-dcdf39712fb3) + +### using token to access resources (get or header) +![Snipaste_2023-10-02_06-17-29](https://github.com/FoskyM/flarum-oauth-center/assets/39661663/aa79ad3b-a480-4d09-9159-359be4518f4b) +![Snipaste_2023-10-02_06-17-42](https://github.com/FoskyM/flarum-oauth-center/assets/39661663/5054ac5b-da79-4db3-9703-94e10a1cde5f) diff --git a/docs/zh.md b/docs/zh.md new file mode 100644 index 0000000..1b4dd92 --- /dev/null +++ b/docs/zh.md @@ -0,0 +1,91 @@ +### 配置项 +![Snipaste_2023-10-02_06-15-33](https://github.com/FoskyM/flarum-oauth-center/assets/39661663/0e8352bf-0aeb-4605-bd84-aaedf8cae0e8) +#### 配置项说明 +- `允许隐式授权` response_type=token 的方式，令牌直接通过 hash 返回给客户端，详细说明可百度 +- `强制状态验证` state 参数必须存在 +- `精确的重定向 URI` 传参时的重定向 URI 必须和创建应用时填写的一致 +- `令牌有效期` 令牌的有效期，单位为秒 + +### 创建应用 +![Snipaste_2023-10-02_06-15-52](https://github.com/FoskyM/flarum-oauth-center/assets/39661663/e9879852-f4ec-4a04-9f81-58004692493c) +#### 应用创建说明 +- `应用名称` 应用的名称 +- `应用描述` 应用的描述 +- `应用图标` 应用的图标，可选 +- `应用主页` 应用的主页，可选 +- `应用回调地址` 应用的回调地址，必填，多个地址使用空格分隔（不推荐单个应用使用多个地址） +- `权限` 可选（不清楚的话不要填） +- `授权类型` 可选（不清楚的话不要填） +- `应用 ID` 和 `应用密钥` 用于客户端认证，添加应用时自动生成，不要泄露给其他人 + +### 设置资源控制器的权限 (user.read 项是默认生成的权限) +![Snipaste_2023-10-02_06-16-06](https://github.com/FoskyM/flarum-oauth-center/assets/39661663/31648ad2-4326-47e0-9d26-c0e3b2f30f8d) +大部分人只需要 `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 应用一样使用 +![Snipaste_2023-10-02_06-16-31](https://github.com/FoskyM/flarum-oauth-center/assets/39661663/1632672e-e631-41bc-b794-40428157b41c) + +### 授权后获取令牌 +![Snipaste_2023-10-02_06-17-00](https://github.com/FoskyM/flarum-oauth-center/assets/39661663/52f1b984-345b-4e09-8b8c-dcdf39712fb3) + +### 使用令牌获取资源 (使用 get 或 header 方式) +![Snipaste_2023-10-02_06-17-29](https://github.com/FoskyM/flarum-oauth-center/assets/39661663/aa79ad3b-a480-4d09-9159-359be4518f4b) +![Snipaste_2023-10-02_06-17-42](https://github.com/FoskyM/flarum-oauth-center/assets/39661663/5054ac5b-da79-4db3-9703-94e10a1cde5f)