diff --git a/docs/config.ts b/docs/config.ts index fcafd177..da29865e 100644 --- a/docs/config.ts +++ b/docs/config.ts @@ -69,6 +69,7 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] { { text: '概览', link: '' }, { text: '快速开始', link: 'quick-start' }, { text: '部署说明', link: 'deployment' }, + { text: 'SSO 登录配置', link: 'sso' }, { text: '启动 Server', link: 'server' }, { text: '接入 Agent', link: 'agent' }, { text: '发布第一份配置', link: 'first-site' }, diff --git a/docs/guide/deployment.md b/docs/guide/deployment.md index 8ca808d1..a4f6cf61 100644 --- a/docs/guide/deployment.md +++ b/docs/guide/deployment.md @@ -93,34 +93,6 @@ go run . 默认监听 `3000` 端口。 -## 认证源登录配置 - -OpenFlare 支持通过认证源配置 GitHub OAuth 或标准 OIDC 登录入口。认证源保存在数据库中，不通过环境变量配置。 - -配置步骤： - -1. 登录管理端，进入“设置 -> 系统设置 -> 配置认证源”。 -2. 新增认证源，选择 `GitHub` 或 `OIDC`。 -3. 填写 `Name`、展示名称、Client ID、Client Secret。OIDC 还需要填写 Discovery URL。 -4. 在第三方平台配置 Redirect URI / Callback URL。 -5. 回到 OpenFlare 启用认证源。 - -回调地址格式固定为： - -```text -/oauth/<认证源 Name> -``` - -例如 OpenFlare 访问地址为 `https://openflare.example.com`，认证源 `Name` 为 `github`，则第三方平台中应填写： - -```text -https://openflare.example.com/oauth/github -``` - -`Name` 是认证源唯一标识，只能包含字母、数字、短横线或下划线，并且必须以字母或数字开头。修改 `Name` 后，第三方平台中的回调地址也必须同步修改。 - -启用后的认证源会显示在登录页。第三方账号首次登录时，如果已经绑定本地用户会直接登录；如果未绑定且允许注册，会自动创建普通用户；如果未绑定且关闭注册，需要使用已有本地账号完成绑定。 - ## Swagger 登录管理端后访问： diff --git a/docs/guide/index.md b/docs/guide/index.md index ce722b56..3343c22b 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -6,9 +6,10 @@ 1. [快速开始](./quick-start.md)：用 Docker Compose 启动 Server，并完成首次登录。 2. [部署说明](./deployment.md)：查看生产部署、Agent 一键安装、联调与升级。 -3. [启动 Server](./server.md)：了解源码启动、前端构建和 Swagger 入口。 -4. [接入 Agent](./agent.md)：选择 `agent_token` 或 `discovery_token`，让节点上线。 -5. [发布第一份配置](./first-site.md)：创建网站配置，发布并确认节点应用。 -6. [升级与维护](./upgrade.md)：了解升级、卸载、验证和日常维护入口。 +3. [SSO 登录配置](./sso.md)：配置 GitHub OAuth 或标准 OIDC 登录入口。 +4. [启动 Server](./server.md)：了解源码启动、前端构建和 Swagger 入口。 +5. [接入 Agent](./agent.md)：选择 `agent_token` 或 `discovery_token`，让节点上线。 +6. [发布第一份配置](./first-site.md)：创建网站配置，发布并确认节点应用。 +7. [升级与维护](./upgrade.md)：了解升级、卸载、验证和日常维护入口。 如果你要参与开发，先阅读 [设计](../design/) 与 [开发约束](../design/development.md)，再进入代码修改。 diff --git a/docs/guide/sso.md b/docs/guide/sso.md new file mode 100644 index 00000000..40a4175b --- /dev/null +++ b/docs/guide/sso.md @@ -0,0 +1,102 @@ +# SSO 登录配置 + +OpenFlare 支持通过认证源配置第三方登录入口。当前支持 GitHub OAuth 与标准 OIDC Provider，例如 Logto、authentik、Keycloak、Casdoor 等。 + +认证源配置完成并启用后，会显示在登录页的第三方账号登录区域。用户可以通过第三方账号登录，也可以在已登录状态下把第三方账号绑定到当前本地账号。 + +## 使用前准备 + +你需要先准备： + +| 项目 | 说明 | +| --- | --- | +| OpenFlare 访问地址 | 用户浏览器实际访问的地址，例如 `https://openflare.example.com` | +| 认证源名称 | OpenFlare 内部唯一标识，例如 `github`、`company-oidc` | +| Client ID | 第三方平台创建应用后提供 | +| Client Secret | 第三方平台创建应用后提供 | +| OIDC Discovery URL | 仅 OIDC 需要，例如 `https://idp.example.com/.well-known/openid-configuration` | + +认证源名称只能包含字母、数字、短横线或下划线，并且必须以字母或数字开头。认证源名称会出现在回调地址中，保存后如需修改名称，也必须同步修改第三方平台中的回调地址。 + +## 回调地址 + +第三方平台中的 Redirect URI / Callback URL 填写格式为： + +```text +/oauth/<认证源名称> +``` + +示例： + +```text +https://openflare.example.com/oauth/github +https://openflare.example.com/oauth/company-oidc +``` + +在管理端新增或修改认证源时，表单会根据当前浏览器访问地址和你输入的认证源名称自动显示应填写的回调地址。 + +## 配置 GitHub 登录 + +1. 在 GitHub 创建 OAuth App。 +2. `Homepage URL` 填写 OpenFlare 访问地址。 +3. `Authorization callback URL` 填写 OpenFlare 显示的回调地址，例如 `https://openflare.example.com/oauth/github`。 +4. 复制 GitHub 提供的 Client ID 和 Client Secret。 +5. 登录 OpenFlare 管理端，进入“设置 -> 系统设置 -> 配置认证源”。 +6. 新增认证源，类型选择 `GitHub`。 +7. 填写认证源名称、展示名称、Client ID、Client Secret。 +8. Scope 默认使用 `user:email`，通常无需修改。 +9. 保存并启用认证源。 + +启用后，登录页会显示对应的 GitHub 登录按钮。 + +## 配置 OIDC 登录 + +1. 在 OIDC Provider 中创建应用或客户端。 +2. 应用类型选择 Web / Confidential Client。 +3. Redirect URI / Callback URL 填写 OpenFlare 显示的回调地址，例如 `https://openflare.example.com/oauth/company-oidc`。 +4. 复制 Client ID 和 Client Secret。 +5. 获取 Provider 的 Discovery URL，通常以 `/.well-known/openid-configuration` 结尾。 +6. 登录 OpenFlare 管理端，进入“设置 -> 系统设置 -> 配置认证源”。 +7. 新增认证源，类型选择 `OIDC`。 +8. 填写认证源名称、展示名称、Client ID、Client Secret、OIDC Discovery URL。 +9. Scope 默认使用 `openid profile email`。如果 Provider 限制了 scope，请按 Provider 允许的值调整。 +10. 保存并启用认证源。 + +启用后，登录页会显示对应的 OIDC 登录按钮。 + +## 登录与绑定行为 + +第三方账号回到 OpenFlare 后按以下规则处理： + +| 场景 | 行为 | +| --- | --- | +| 第三方账号已绑定本地用户 | 直接登录 | +| 用户已登录并发起第三方授权 | 绑定到当前本地用户 | +| 第三方账号未绑定，且允许注册 | 自动创建普通用户并绑定 | +| 第三方账号未绑定，且关闭注册 | 要求输入已有本地账号密码完成绑定 | + +如果希望只允许已有用户使用 SSO，可以关闭用户注册。未绑定的第三方账号会进入绑定已有账号流程。 + +## 修改认证源 + +修改认证源时，Client Secret 输入框留空表示保留已有密钥；填写新值则会覆盖保存。 + +如果修改了认证源名称，回调地址也会随之变化。你必须到第三方平台同步修改 Redirect URI / Callback URL，否则第三方平台会拒绝回调或返回错误。 + +## 常见问题 + +### 返回 `invalid_scope` + +说明第三方平台不允许当前配置的 Scope。OIDC 默认 Scope 是 `openid profile email`，GitHub 默认 Scope 是 `user:email`。请到认证源编辑页调整 Scope，或在第三方平台放行对应 Scope。 + +### 提示回调地址不匹配 + +检查第三方平台中配置的 Redirect URI / Callback URL 是否与 OpenFlare 表单提示完全一致。协议、域名、端口和路径都必须一致。 + +### 登录页没有显示第三方登录按钮 + +检查认证源是否已启用，并确认 Client ID 和 Client Secret 已保存。启用认证源前，OpenFlare 会校验这些字段。 + +### 已经保存 Client Secret，但列表不显示明文 + +这是预期行为。OpenFlare 不会通过 API 回显 Client Secret，只显示该密钥是否已配置。 diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index 9e2798a3..98aa6b6f 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -80,36 +80,7 @@ go run . --port 3000 --log-dir ./logs * 管理端支持手动清理时留空保留天数，以直接删除对应数据集的全部历史记录。 * 第三方登录不再通过 `GitHubOAuthEnabled`、`GitHubClientId`、`GitHubClientSecret` 作为主配置入口；这些旧 Option 仅用于升级时迁移默认 GitHub 认证源。 * 微信登录旧 Option 保留为兼容字段，但管理端不再提供微信登录配置入口。 -* Turnstile 旧 Option 与后端校验能力保留，已有配置仍会生效；本版本移除了旧 `OAuth / WeChat / Turnstile` 集成卡片。 - -## 认证源配置 - -认证源配置保存在数据库 `auth_sources` 表，由管理端“设置 -> 系统设置 -> 配置认证源”维护，不通过环境变量或启动参数配置。 - -当前支持： - -| 类型 | 必填配置 | 默认 Scope | 说明 | -| --- | --- | --- | --- | -| `github` | Name、Client ID、Client Secret | `user:email` | 使用 GitHub OAuth 登录 | -| `oidc` | Name、Client ID、Client Secret、OIDC Discovery URL | `openid profile email` | 适用于 Logto、authentik 等标准 OIDC Provider | - -启用后的认证源会通过 `/api/status` 暴露公开字段并显示在登录页。`Client Secret` 不会通过 API 回显。 - -`Name` 是认证源的唯一标识，也会作为 OAuth/OIDC 回调路径的一部分。第三方平台中的 Redirect URI / Callback URL 应配置为： - -```text -/oauth/<认证源 Name> -``` - -例如 OpenFlare 访问地址为 `https://openflare.example.com`，认证源 `Name` 为 `github` 时，回调地址为： - -```text -https://openflare.example.com/oauth/github -``` - -认证源 `Name` 只能包含字母、数字、短横线或下划线，并且必须以字母或数字开头。修改 `Name` 后必须同步更新第三方平台中的回调地址。 - -外部账号绑定保存在 `external_accounts` 表。第三方账号未绑定时，如果允许注册则自动创建普通用户；如果关闭注册，则只能绑定已有本地账号。 +* Turnstile 旧 Option 与后端校验能力保留，已有配置仍会生效； ## OpenResty 参数