mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-09-29 22:06:38 +08:00
ryan
600a7acdfb
- 删除未经验证的环境要求（Docker 版本号、浏览器条目）与括号废话 - 故障排查改为真实处理路径（升级→重新发布→强制同步→重建 Agent→提交 issue），删除仅开发时用的排障章节 - 删除设计文档中的测试与验收、实现检查清单、贡献者阅读建议等开发内容 - 修正与代码不符的事实：reset-passwd 命令名、证书续签窗口 7 天、Pages 检查间隔 1440 分钟、Relay vhost 端口 8080、SSO 仅支持 OIDC 等 - 去除口语化表述与无意义括号，改写「不是…而是…」句式 - 同步修正文档站链接锚点，构建验证通过
86 lines
4.0 KiB
Markdown
86 lines
4.0 KiB
Markdown
# SSO 登录配置
|
|
|
|
你会学到：如何为 OpenFlare 配置 OIDC 第三方登录入口、填写回调地址，以及第三方账号如何绑定本地用户。
|
|
|
|
OpenFlare 通过 OIDC 认证源接入第三方登录。任意提供标准 OIDC Discovery 的服务（如 Google、Keycloak、authentik、Logto、Casdoor 等）都可以接入。
|
|
|
|
认证源配置完成并启用后，会显示在登录页的第三方账号登录区域。用户可以通过第三方账号登录，也可以在已登录状态下把第三方账号绑定到当前本地账号。
|
|
|
|
## 使用前准备
|
|
|
|
| 项目 | 说明 |
|
|
| --- | --- |
|
|
| 服务器访问地址 | 在管理端「系统设置」->「系统设置」选项卡 ->「通用设置」中配置，须与用户浏览器实际访问的地址一致（协议、域名、端口） |
|
|
| 认证源名称 | OpenFlare 内部唯一标识，例如 `company-oidc` |
|
|
| Client ID | 第三方平台创建应用后提供 |
|
|
| Client Secret | 第三方平台创建应用后提供 |
|
|
| OIDC Discovery URL | 例如 `https://idp.example.com/.well-known/openid-configuration` |
|
|
|
|
认证源名称只能包含字母、数字、短横线或下划线，并且必须以字母或数字开头。
|
|
|
|
## 回调地址
|
|
|
|
第三方平台中的 Redirect URI / Callback URL 固定填写：
|
|
|
|
```text
|
|
<服务器访问地址>/login
|
|
```
|
|
|
|
例如服务器访问地址为 `https://openflare.example.com` 时：
|
|
|
|
```text
|
|
https://openflare.example.com/login
|
|
```
|
|
|
|
回调地址只与「服务器访问地址」相关，不包含认证源名称。第三方平台授权完成后会跳转到该地址，OpenFlare 登录页携带授权码完成登录或绑定。
|
|
|
|
## 配置 OIDC 登录
|
|
|
|
1. 在 OIDC Provider 中创建应用或客户端，应用类型选择 Web / Confidential Client。
|
|
2. Redirect URI / Callback URL 填写 `<服务器访问地址>/login`。
|
|
3. 复制 Client ID 和 Client Secret。
|
|
4. 获取 Provider 的 Discovery URL，通常以 `/.well-known/openid-configuration` 结尾。
|
|
5. 登录 OpenFlare 管理端，进入左侧导航 **「系统设置」**，选择 **「安全设置」** 选项卡，在 **「认证源管理」** 栏目中新增认证源。
|
|
6. 类型选择 `OIDC`，填写认证源名称、展示名称、Client ID、Client Secret、OIDC Discovery URL。
|
|
7. Scope 默认使用 `openid profile email`。如果 Provider 限制了 scope，请按 Provider 允许的值调整。
|
|
8. 保存并启用认证源。
|
|
|
|
启用后，登录页会显示对应的第三方登录按钮。
|
|
|
|
## 登录与绑定行为
|
|
|
|
第三方账号回到 OpenFlare 后按以下规则处理：
|
|
|
|
| 场景 | 行为 |
|
|
| --- | --- |
|
|
| 第三方账号已绑定本地用户 | 直接登录 |
|
|
| 用户已登录并发起第三方授权 | 绑定到当前本地用户 |
|
|
| 第三方账号未绑定，且允许注册 | 自动创建普通用户并绑定 |
|
|
| 第三方账号未绑定，且关闭注册 | 要求输入已有本地账号密码完成绑定 |
|
|
|
|
如果希望只允许已有用户使用 SSO，可以关闭用户注册。未绑定的第三方账号会进入绑定已有账号流程。
|
|
|
|
## 修改认证源
|
|
|
|
修改认证源时，Client Secret 输入框留空表示保留已有密钥；填写新值则会覆盖保存。
|
|
|
|
修改认证源名称不会影响回调地址，无需同步修改第三方平台配置。
|
|
|
|
## 常见问题
|
|
|
|
### 返回 `invalid_scope`
|
|
|
|
说明第三方平台不允许当前配置的 Scope。OIDC 默认 Scope 是 `openid profile email`。请到认证源编辑页调整 Scope，或在第三方平台放行对应 Scope。
|
|
|
|
### 提示回调地址不匹配
|
|
|
|
检查第三方平台中配置的 Redirect URI / Callback URL 是否与 `<服务器访问地址>/login` 完全一致。协议、域名、端口和路径都必须一致。
|
|
|
|
### 登录页没有显示第三方登录按钮
|
|
|
|
检查认证源是否已启用，并确认 Client ID 和 Client Secret 已保存。启用认证源前，OpenFlare 会校验这些字段。
|
|
|
|
### 已经保存 Client Secret，但列表不显示明文
|
|
|
|
这是预期行为。OpenFlare 不会通过 API 回显 Client Secret，只显示该密钥是否已配置。
|