OIDC 单点登录

用途与权限

将后台登录接入兼容 OpenID Connect 的身份提供商，并支持启用、连接测试和独占 SSO。配置包含客户端密钥；当前接口要求登录，但未额外执行系统管理员角色校验，因此部署时应只向可信管理员开放后台入口。

入口

左侧菜单“系统设置 → OIDC 单点登录”，路由为 /settings/oidc。

页面总览

页面包含 Provider 名称、登录按钮名称、Issuer、Client ID、Client Secret、Scopes、Redirect URI、启用和独占登录配置。

主要操作

1. 在身份提供商创建 OIDC 客户端，并登记系统回调地址。
2. 填写 Issuer 根地址、Client ID 和 Client Secret；首次保存必须提供 Secret。
3. Scopes 通常使用 openid profile email；Redirect URI 留空时使用系统默认值。
4. 先点击“测试连接”，确认发现文档和客户端配置可用，再保存并启用。
5. 使用独立测试账号验证 SSO 登录和个人资料绑定后，才考虑开启独占登录。

字段/限制

• issuer 是 Discovery 文档所在 OIDC Issuer 根地址，不是授权端点 URL。
• 编辑已有配置时 Secret 留空表示不修改；首次保存不能为空。
• Redirect URI 必须与身份提供商登记值完全一致。
• 开启 exclusive 后，本地密码登录可能被隐藏；只有配置的旁路条件才能恢复本地入口。
• 修改前应保留一个可恢复的系统管理员会话，防止把所有管理员锁在系统外。

常见错误

• 测试连接失败：检查 Issuer TLS、Discovery 文档、Client ID/Secret 和服务端网络。
• redirect_uri_mismatch：身份提供商登记地址与页面实际回调地址不一致。
• 登录后无法关联用户：检查 sub、邮箱等声明和用户匹配策略。
• 开启独占后无法登录：使用已配置的旁路机制恢复，再修正 OIDC 配置。

关联 API

• GET|PUT /api/v1/admin/oidc/config
• POST /api/v1/admin/oidc/test
• GET /api/v1/auth/login-options
• GET /api/v1/auth/oidc/authorize
• GET /api/v1/auth/oidc/callback