外观
GitHub、Google 与通用 OIDC / SSO
RelayDock 可作为第三方身份登录的客户端。自己的 Chitanda SSO、Keycloak、Authentik 等身份服务负责认证,RelayDock 仍负责本地账号和服务授权。
接入前准备
- 控制端有稳定的 HTTPS 规范域名。
- 身份服务支持所选 OAuth/OIDC 流程;通用 OIDC 需提供标准 discovery 元数据。
- 保留一个经过验证的本地管理员登录方式,避免配置错误时锁在外面。
- 明确是否允许自动注册,以及是否允许按邮箱自动关联已有账号。
通用 OIDC 配置
- 在身份提供商创建应用,准备 Client ID 与 Client Secret。
- 在 系统设置 → 快捷登录 → 通用 OIDC 启用并填写 Issuer。
- 配置按钮名称,例如“企业统一登录”。
- 将面板显示的完整 Redirect URI 注册到身份提供商;通常为
https://panel.example.com/api/oauth/oidc/callback,但以页面为准。 - 保存后在独立浏览器会话完成一次手动登录。
- 核对落到的本地账号、角色、服务授权和退出行为。
Issuer 不是任意登录网页 URL,应能通过 /.well-known/openid-configuration 等标准发现机制取得元数据。不要在客户端 Secret 中填写用户密码。
GitHub 与 Google
分别创建对应平台应用并填写其专用配置。回调常见为 /api/oauth/github/callback 与 /api/oauth/google/callback,复制当前页面的值,不混用 OIDC 回调。
Google 登录涉及浏览器访问授权页面,也涉及控制端访问外部元数据/令牌接口。国内网络下可能是不同阶段超时,不能只看按钮名称判断根因。
自动注册与邮箱关联
| 开关 | 含义 | 配置前考虑 |
|---|---|---|
| 首次第三方登录自动注册 | 为新身份创建本地账号 | 允许哪些身份进入、是否仍需服务授权 |
| 邮箱一致自动关联 | 将第三方身份映射到既有账号 | 邮箱验证、冲突、身份提供商信任边界 |
| 登录页自动检测 OIDC 状态 | 尝试利用已有 SSO 会话 | 浏览器限制、身份服务支持及循环处理 |
高权限账号的身份关联应特别谨慎,不能单凭界面显示同一个邮箱就认定安全。测试新身份时确认没有错误关联到管理员。
自动检测与界面加载
先验证手动登录,再打开自动检测。未登录 SSO 的用户应能稳定停留在本地登录页;已登录用户按策略完成认证后进入后台。不能反复闪烁“第三方登录/Google”或循环跳转。
当前前端等待登录初始化完成后展示表单,减少品牌与按钮异步到达造成的界面跳变。旧静态资源缓存可能让浏览器仍使用旧版,见版本检查。
回调失败排查
| 现象 | 定位方向 |
|---|---|
| 授权页面根本打不开 | 浏览器网络、DNS、地区访问 |
| 点击后仍停在本站并 504 | 本站反代、后端日志、服务端访问身份服务 |
| redirect_uri_mismatch | 回调域名、路径、协议和提供商白名单 |
| state / nonce / code 错误 | 重复回调、跨会话、超时或认证校验失败;重新发起合法登录 |
| 登录后错误账号或无服务 | 本地身份映射、角色及授权 |
不要通过关闭 state/nonce、放开任意回调或绕过签名校验解决登录问题。
