連接 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 以外的宣告中，請設定群組宣告名稱；需要的 話可將群組對應到角色（SSO 永遠無法授予擁有者角色）。
5. 選擇成員資格原則（自動加入每個工作區，或要求逐一工作區邀請），開啟 使用 OpenID Connect 登入，然後按下儲存連線。
6. 按下測試連線——伺服器會抓取簽發者的探索文件並確認其端點，因此出現 綠色提示表示除了瀏覽器往返之外的一切都正常運作。若也要檢查用戶端註冊， 請使用下方的檢查工具。
7. 實際登入一次：網頁連線畫面會顯示以 OpenID Connect 登入，或直接開啟 https://<your-server>/oidc/login。

宣告（電子郵件、名稱、群組）由你的伺服器透過 TLS 從簽發者的權杖端點讀取 ——瀏覽器從不提供這些資料，因此不涉及本機的 JWT 簽章驗證。應允許該用戶端 要求 openid profile email 範圍，這正是 Control Center 所要求的。

由於該 TLS 通道是唯一驗證宣告的機制，簽發者 URL 必須是 https——純文字 的簽發者會讓任何路徑上的攻擊者大量偽造身分。http 僅適用於回送位址的簽發 者（localhost、127.0.0.1、::1），供本機開發使用。

公開用戶端還是機密用戶端？

預設——也是建議——的形態是使用授權碼流程搭配 PKCE（RFC 7636）的 公開用戶端：伺服器持有的一次性授權碼驗證器取代了密鑰，而權杖交換會 繫結到發起它的授權要求。沒有可外洩的密鑰，而且被竊取的授權碼少了驗證器也 毫無用處。有些供應商在建立時把這稱為「SPA」或「原生」用戶端類型。

如果你的供應商核發的是機密用戶端，請在供應商端將該用戶端標記為公開 （無論哪種方式都會維持 PKCE），或把用戶端密鑰貼到連線的**用戶端密鑰 （選填）**欄位。密鑰儲存在伺服器權限 0600 的機密檔案中（絕不會存進 資料庫），以 client_secret_post 傳送到權杖端點，且永遠不會透過 RPC 回 傳；儲存時將欄位留白會保留已儲存的密鑰。當登入在權杖交換階段失敗時，伺服 器日誌會寫出供應商自己的錯誤（invalid_client 幾乎都表示密鑰缺少或有誤）。

可達性

登入本身由瀏覽器中介：簽發者只會把使用者的瀏覽器重新導向回 /oidc/callback，並由你的伺服器對權杖端點發出對外的 HTTPS 呼叫——不需要 來自簽發者的連入連線，因此只要使用者的瀏覽器能連到伺服器，位於 NAT 後方的 伺服器也能運作（區域網路、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