diff --git a/apps/docs/.vitepress/config.ts b/apps/docs/.vitepress/config.ts index d1a15ad..a3c71b0 100644 --- a/apps/docs/.vitepress/config.ts +++ b/apps/docs/.vitepress/config.ts @@ -35,6 +35,7 @@ export default defineConfig({ { text: "账号与消息", items: [ + { text: "认识登录中心与应用授权", link: "/account/login-authorization" }, { text: "管理个人内容", link: "/account/personal-content" }, { text: "查看通知和私信", link: "/messages/overview" }, ], diff --git a/apps/docs/content/account/login-authorization.md b/apps/docs/content/account/login-authorization.md new file mode 100644 index 0000000..ae02ba3 --- /dev/null +++ b/apps/docs/content/account/login-authorization.md @@ -0,0 +1,55 @@ +# 认识 CC98 登录中心与应用授权 + +有些应用会提供“使用 CC98 登录”。点击后,浏览器会进入 `openid.cc98.org`,由 CC98 登录中心确认身份并询问是否授权。应用拿到的是有范围、有期限的令牌,不会收到用户填写的密码。 + +## 登录和授权是两件事 + +登录中心先确认当前用户是谁,再按照授权页面列出的范围向应用发放令牌。用户可以拒绝授权,也可以在之后撤销已经授予的权限。 + +这套流程使用 OpenID Connect(OIDC)。OIDC 在 OAuth 2.0 的授权能力上增加了身份信息,让应用既能确认当前用户,也能在用户同意后访问相应的 CC98 服务。 + +目前 CC98 登录中心支持用户名和密码、通行密钥等认证方式。应用只接收登录结果,因此登录中心以后增加新的认证方式时,采用标准 OIDC 的应用通常不需要重新制作自己的登录页面。 + +## 跳转登录会经过哪些步骤 + +1. 在应用中点击“使用 CC98 登录”。 +2. 浏览器跳转到 `https://openid.cc98.org`。 +3. 在登录中心完成身份验证,并查看应用名称、说明和请求的权限。 +4. 同意后,登录中心把浏览器送回应用登记过的地址。 +5. 应用取得短期访问令牌,再用它访问获准的 CC98 服务。 + +登录中心返回的授权码只能使用一次。支持 PKCE 的应用还会为这次登录生成一组临时校验信息,即使授权码在跳转过程中被截获,没有对应校验信息也无法换取令牌。 + +## 授权范围决定应用能做什么 + +授权页面会列出应用请求的范围。常见范围包括: + +- `openid`:确认当前用户身份。 +- `profile`:读取基本资料。 +- `cc98-api`:访问 CC98 论坛 API。 +- `offline_access`:在用户离开登录页面后继续刷新登录状态。 + +应用只能请求注册时允许的范围。授权前应核对应用名称和权限,范围明显超过用途时可以拒绝。 + +## 几种凭证有什么区别 + +| 名称 | 用途 | +| -------- | -------------------------------------- | +| 授权码 | 登录中心返回的一次性凭证,用来换取令牌 | +| 访问令牌 | 调用 CC98 服务的短期凭证 | +| 刷新令牌 | 访问令牌过期后申请新令牌 | +| 身份令牌 | 由登录中心签发的用户身份说明 | + +授权码、访问令牌、刷新令牌和浏览器 Cookie 都属于敏感信息。不要把它们发给其他人,也不要复制到公开 issue、聊天记录或截图中。 + +## 核对登录页面和管理授权 + +输入 CC98 密码或使用通行密钥前,先确认地址栏属于 `https://openid.cc98.org`。授权页面还应显示应用名称、说明和请求的范围。 + +已经授予的权限可以在 [CC98 登录中心的授权管理页面](https://openid.cc98.org/Grant) 查看和撤销。撤销授权不会删除 CC98 账号或论坛内容,但应用将无法继续刷新令牌,已有的短期访问令牌会在到期后失效。发现异常授权时,先撤销对应应用;怀疑密码泄露时,再前往账号管理页面修改密码。 + +## 开发者如何接入 + +开发者可以在 [CC98 登录中心创建应用](https://openid.cc98.org/App/Create),登记应用名称、重定向地址、允许的 CORS 来源和授权范围。浏览器前端适合使用 Authorization Code + PKCE,并使用 `S256` 生成校验信息。浏览器代码无法保守客户端密钥,因此纯前端应用不应依赖 Client Secret。 + +CC98 登录中心的标准端点可以从 [OpenID Connect discovery](https://openid.cc98.org/.well-known/openid-configuration) 获取。论坛帖子 [CC98 OAuth2 使用记录](https://cc98.shellraining.xyz/topic/6468549) 也记录了创建应用、配置回调地址和选择授权范围的过程。 diff --git a/apps/docs/content/guide/getting-started.md b/apps/docs/content/guide/getting-started.md index a573e58..e575b15 100644 --- a/apps/docs/content/guide/getting-started.md +++ b/apps/docs/content/guide/getting-started.md @@ -8,6 +8,8 @@ > 密码只应填写在 CC98 的登录页面。不要把密码、登录令牌或浏览器 Cookie 发给其他人。 +部分应用会跳转到 CC98 登录中心完成身份验证。有关跳转登录、授权范围和撤销授权的说明,见[认识 CC98 登录中心与应用授权](/account/login-authorization)。 + ## 安装到桌面 支持 PWA 的浏览器可以把 CC98 安装到桌面或主屏幕。安装入口通常位于地址栏或浏览器菜单中,名称可能是“安装应用”“添加到主屏幕”或“创建快捷方式”。安装后会以独立窗口打开,账号和外观设置仍由当前浏览器管理。