连接 OpenID Connect 提供方

当你的身份提供方使用 OpenID Connect 而非 SAML 时，请参照本指南。任何通过 OIDC 认证的签发者都适用——Pocket ID、Keycloak、Auth0、Zitadel、Google Workspace 之类 都遵循同样的步骤；区别只在于提供方展示这些值的位置。

前提条件

• 一个可以在其中创建客户端的 OIDC 提供方——记下它的客户端 ID 和签发者 URL （即 .well-known/openid-configuration 文档所在的基址），以及当客户端属于机密 类型时所需的客户端密钥（公共 PKCE 客户端没有密钥），
• 一台由你管理的 Control Center 服务器（即服务器所有者）。

步骤

1. 打开设置 → 服务器 → 单点登录，切换到 OpenID Connect。
2. 填写签发者 URL、客户端 ID，以及提供方签发了密钥时的客户端密钥 （可选）。Control Center 会从签发者的标准发现文档中发现各个端点——无需针对 不同提供方分别配置。
3. 在提供方处，为该客户端注册重定向地址 https://<your-server>/oidc/callback。
4. 如果你的组位于 groups 以外的 claim 下，请设置 组 claim 名称；如有需要，可 把组映射到角色（SSO 永远无法授予所有者角色）。
5. 选择成员资格策略（自动加入每个工作区，或要求按工作区发送邀请），打开使用 OpenID Connect 登录，然后点击保存连接。
6. 点击测试连接——服务器会获取签发者的发现文档并确认其各个端点，因此出现绿色 提示意味着除浏览器往返之外的一切都正常。若要同时检查客户端注册情况，请使用 下方的检查器。
7. 实际登录一次：Web 连接界面会显示使用 OpenID Connect 登录，也可以直接打开 https://<your-server>/oidc/login。

Claim（电子邮件、姓名、组）由你的服务器通过 TLS 从签发者的令牌端点读取——浏览器 从不提供它们，因此不涉及本地 JWT 签名校验。应允许该客户端请求 openid profile email 作用域，这正是 Control Center 所请求的内容。

由于该 TLS 通道是认证 claim 的唯一依据，签发者 URL 必须为 https——明文签发者 会让任何路径上的攻击者随意伪造身份。仅在本地开发时，回环签发者（localhost、 127.0.0.1、::1）才接受 http。

公共客户端还是机密客户端？

默认（也是推荐的）形态是采用带 PKCE（RFC 7636）的授权码流程的公共客户端： 服务器持有的一次性 code verifier 取代了密钥，令牌交换与发起它的授权请求绑定。没有 可泄露的密钥，而被窃取的授权码在没有 verifier 的情况下毫无用处。有些提供方在创建 客户端时把这种类型称为 “SPA” 或 “native”。

如果你的提供方签发的是机密客户端，要么在提供方处把该客户端标记为公共客户端 （两种情况下 PKCE 都保持启用），要么把客户端密钥粘贴到连接的客户端密钥（可选） 字段中。密钥存储在服务器的 0600 密钥文件中（绝不会存入数据库），以 client_secret_post 的方式发送到令牌端点，且从不通过 RPC 返回；保存时把该字段留空 会保留已存储的密钥。当登录在令牌交换环节失败时，服务器日志会记录提供方自己的错误 （invalid_client 几乎总是意味着密钥缺失或错误）。

可达性

登录本身以浏览器为中介：签发者只是把用户的浏览器重定向回 /oidc/callback，而你的 服务器会向令牌端点发起出站的 HTTPS 调用——不需要来自签发者的入站连接，因此只要 用户的浏览器能访问到，位于 NAT 之后的服务器也能正常工作（LAN、VPN、Tailscale 或 隧道）。SCIM 预配是例外：IdP 会直接调用你的服务器，这需要隧道或公网 URL—— 参见用 SCIM 预配用户。

从本页检查你的配置

下面的检查器在你的浏览器中运行。它直接获取你签发者的发现文档，因此本站永远看不到 该文档，并按服务器的规则进行检查：https 签发者与文档一致、端点位于签发者自己的源 上、PKCE S256，以及你的客户端类型所需的令牌认证方式。提供客户端 ID 和服务器地址 后，它还可以打开一次测试登录，以显示该客户端及其重定向 URI 是否已注册。它绝不会 索取客户端密钥。

Runs in your browserYour browser fetches the discovery document straight from your issuer. Add a server address and it also asks that server which sign-in methods it offers. This site never receives what you type.

Issuer URL

Client ID (optional)

Needed for the test sign-in.

Groups claim (optional)

Client type

Public, PKCE only Confidential, has a client secret

Never paste the secret here. The check only needs to know whether one exists.

Server address (optional)

The address your users open. Adds a reachability check and a test sign-in.

Paste the discovery document instead

Discovery document JSON

For providers that block other sites from reading it.

Check issuer