diff --git a/docs/_sidebar.md b/docs/_sidebar.md index db65697..b166ec8 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -12,5 +12,7 @@ * [Campux 前后端和系统配置](usage/campux) * [CampuxBot](usage/bot) * [CampuxUtility](usage/utility) +* [扩展](extension/) + * [OAuth 2.0](extension/oauth) * [开发](develop/) * [Campux 前后端](develop/campux) \ No newline at end of file diff --git a/docs/assets/extension_oauth_01.png b/docs/assets/extension_oauth_01.png new file mode 100644 index 0000000..3d86abb Binary files /dev/null and b/docs/assets/extension_oauth_01.png differ diff --git a/docs/assets/extension_oauth_02.png b/docs/assets/extension_oauth_02.png new file mode 100644 index 0000000..07e3248 Binary files /dev/null and b/docs/assets/extension_oauth_02.png differ diff --git a/docs/assets/extension_oauth_03.png b/docs/assets/extension_oauth_03.png new file mode 100644 index 0000000..e68c557 Binary files /dev/null and b/docs/assets/extension_oauth_03.png differ diff --git a/docs/assets/extension_oauth_04.png b/docs/assets/extension_oauth_04.png new file mode 100644 index 0000000..ce2e5c0 Binary files /dev/null and b/docs/assets/extension_oauth_04.png differ diff --git a/docs/deploy/campux.md b/docs/deploy/campux.md index 070d813..5325707 100644 --- a/docs/deploy/campux.md +++ b/docs/deploy/campux.md @@ -36,6 +36,7 @@ docker compose up ```yaml auth: jwt: + # 用户登录 Token 的有效期,单位秒 expire: 21600 secret: <你自定义的 JWT Token 密钥> backend: @@ -63,12 +64,24 @@ mq: new_post: campux_new_post publish_post: campux_publish_post post_cancel: campux_post_cancel + prefix: + # key 前缀 + # 如果你多个Campux系统共用同一个Redis,这里的名称相同的key值每个系统要区分一下 + oauth2_code: campux_oauth2_code hash: # hash 表的名称 # 如果你多个Campux系统共用同一个Redis,这里的名称相同的key值每个系统要区分一下 # post_publish_status: 系统内多个bot发表一个稿件后,会在对应稿件的hash表中记录发表状态以供后端确认发表状态,这个value为hash表前缀 # 默认值为例,ID 为 1 的稿件,发表状态的hash表名为 campux_post_publish_status1 post_publish_status: campux_post_publish_status +oauth2: + server: + # OAuth 2.0 Access Token 的加密密钥 + access_secret: 76f49aa2-4634-4696-81e0-e95fb202e9f3 + # OAuth 2.0 Access Token 的有效期,单位秒 + ak_expire: 1209600 + # OAuth 2.0 授权码的加密密钥 + code_secret: a5c6f609-e5bb-495a-a2b9-160f201049d8 oss: minio: access_key: <你的 MinIO Access Key> diff --git a/docs/extension/README.md b/docs/extension/README.md new file mode 100644 index 0000000..e9481ed --- /dev/null +++ b/docs/extension/README.md @@ -0,0 +1,3 @@ +# 扩展 + +Campux 目前支持 OAuth 2.0 授权的方式进行扩展。 \ No newline at end of file diff --git a/docs/extension/oauth.md b/docs/extension/oauth.md new file mode 100644 index 0000000..4ef64cf --- /dev/null +++ b/docs/extension/oauth.md @@ -0,0 +1,110 @@ +# OAuth 2.0 接入 + +Campux 支持作为 OAuth 2.0 Server 为其他服务提供授权服务。通过这个功能可以快速搭建校内统一鉴权服务。 + +> OAuth 2.0 简介:https://www.ruanyifeng.com/blog/2014/05/oauth_2_0.html + +## 配置 + +管理员前往 `管理` 页,`OAuth 2 应用` 面板,点击 新增。 + +新增 OAuth 2 应用 + +填写应用名称,选择一个 Emoji,点击确定。 + +记录下页面上显示的 `Client ID` 和 `Client Secret`,这两个值将在 OAuth 2.0 授权流程中使用。 + +Client ID 和 Client Secret + +## 用户首次访问授权流程 + +- 假设你有 Campux 部署在 https://campux.com 。 +- 假设你有服务 DemoApp,部署在 https://demoapp.com ,已经在 Campux 配置了 OAuth 2.0 应用,Client ID 为 `7RYtLq8VA45Fiprc`,Client Secret 为 `851de2eb-3fbb-40cc-8354-92a9bdf97fed`。 + - DemoApp 需要实现一个页面,用于接收 Campux 的授权回调,本例中,这个页面的地址是 `https://demoapp.com/oauth2/callback`。 + +### 1. 请求授权 + +用户访问 DemoApp,DemoApp 重定向用户到 Campux 的授权页面: + +``` +https://campux.com/#/auth?client_id=7RYtLq8VA45Fiprc&redirect_uri=https://demoapp.com/oauth2/callback +``` + +- `client_id`:Campux 分配给 DemoApp 的 Client ID。 +- `redirect_uri`:授权成功后,Campux 重定向到 DemoApp 的地址。 +- `state`(可选):一个随机生成的字符串,用于防止 CSRF 攻击。 + +### 2. 用户授权 + +授权页面 + +用户点击 `授权` 按钮,Campux 重定向到 DemoApp 的地址: + +``` +https://demoapp.com/oauth2/callback?code=eyJhbGciOiJIUzI1NiIsInR5cCI6I +``` + +- `code`:授权码,DemoApp 用这个授权码向 Campux 请求访问令牌。 +- `state`(可选):DemoApp 传递的 `state` 参数。 + +*code的有效期为 10 分钟。 + +### 3. DemoApp 换取访问令牌 + +DemoApp 的回调页面收到授权码后,向 Campux 请求访问令牌(建议使用后端请求): + +``` +POST https://campux.com/v1/oauth2/get-access-token +Content-Type: application/json + +{ + "client_id": "7RYtLq8VA45Fiprc", + "client_secret": "851de2eb-3fbb-40cc-8354-92a9bdf97fed", + "code": "eyJhbGciOiJIUzI1NiIsInR5cCI6I", +} +``` + +返回: + +```json +{ + "code": 0, + "msg": "ok", + "data": { + "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" + } +} +``` + +获取访问令牌 + +*Access Token 的有效期可以在后端配置文件中配置 + +### 4. DemoApp 使用 Access Token 请求资源 + +目前只有一个获取用户信息的接口: + +``` +GET https://campux.com/v1/oauth2/get-user-info +Authorization Bearer +``` + +返回: + +```json +{ + "code": 0, + "msg": "ok", + "data": { + "created_at": "2024-04-18T00:49:37.275Z", + "uin": 1010553892, + "user_group": "admin" + } +} +``` + +## 用户再次访问 + +如果 Access Token 未过期,用户再次访问 DemoApp,DemoApp 可以直接使用 Access Token 请求资源。 + +若 Access Token 过期,DemoApp 需要重新按照上述流程获取 Access Token。 \ No newline at end of file