Skip to content

GitHub、Google 与通用 OIDC / SSO ​

RelayDock 可作为第三方身份登录的客户端。自己的 Chitanda SSO、Keycloak、Authentik 等身份服务负责认证,RelayDock 仍负责本地账号和服务授权。

接入前准备 ​

  • 控制端有稳定的 HTTPS 规范域名。
  • 身份服务支持所选 OAuth/OIDC 流程;通用 OIDC 需提供标准 discovery 元数据。
  • 保留一个经过验证的本地管理员登录方式,避免配置错误时锁在外面。
  • 明确是否允许自动注册,以及是否允许按邮箱自动关联已有账号。

通用 OIDC 配置 ​

  1. 在身份提供商创建应用,准备 Client ID 与 Client Secret。
  2. 在 系统设置 → 快捷登录 → 通用 OIDC 启用并填写 Issuer。
  3. 配置按钮名称,例如“企业统一登录”。
  4. 将面板显示的完整 Redirect URI 注册到身份提供商;通常为 https://panel.example.com/api/oauth/oidc/callback,但以页面为准。
  5. 保存后在独立浏览器会话完成一次手动登录。
  6. 核对落到的本地账号、角色、服务授权和退出行为。

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、放开任意回调或绕过签名校验解决登录问题。

操作示例与截图均使用演示数据 · 内容核对于 2026-11-20