單點驗證 - AI Coding Assistant Lingma

本文介紹 QoderWork CN 和 Qoder CN CLI 企業標準版，如何為組織配置單點登入（SSO），支援 SAML 2.0 和 OIDC 兩種協議。

概述

單點登入（SSO）允許組織成員使用企業身份供應商（Identity Provider，IDP）進行認證，無需在 Qoder 管理獨立的登入憑證。Qoder 支援兩種主流的 SSO 協議：

SAML 2.0：基於 XML 的成熟企業級認證標準，廣泛應用於 Okta、Microsoft Entra ID（Azure AD）、OneLogin、阿里雲 IDaaS 等 IDP。
OIDC（OpenID Connect）：構建於 OAuth 2.0 之上的現代身份協議，支援通過 Discovery URL 一鍵自動探索配置，典型供應商包括 Okta、Azure AD、Google Workspace、Auth0、Authing、阿里雲 RAM 等。

SSO 的優勢

增強安全性： 通過你的企業身份供應商進行集中式認證。
改善使用者體驗： 一套憑證即可訪問企業的所有應用程式。
簡化使用者管理： 已驗證網域名稱下的使用者首次登入時自動建立帳號並加入組織。

如何選擇協議？

協議	適用情境
SAML	IDP 僅提供 SAML 協議；需要 IdP 發起登入（IdP-initiated SSO）；已有基於 SAML 的企業認證體系
OIDC	IDP 提供 OIDC / OAuth 2.0；希望通過 Discovery URL 自動探索端點；需要更輕量的 JSON 化整合方式

每個組織同一時間只能啟用一種 SSO 協議。如需切換協議，請先停用當前協議再建立新協議的配置。

前提條件

在配置 SSO 之前，請確保你已具備以下條件：

管理員權限： 你在組織內擁有管理員權限。
身份供應商許可權： 你擁有在組織的 IDP 中建立和配置應用的許可權。
DNS 存取權限：你擁有在組織的郵箱網域名稱添加 TXT 記錄以進行驗證的許可權。

配置流程

無論選擇 SAML 還是 OIDC，SSO 配置過程都包括以下步驟：

步驟 1：驗證郵箱網域名稱

在配置 SSO 之前，你需要先驗證公司郵箱網域名稱的所有權，以確保只有使用已驗證公司郵箱網域名稱的使用者，才能通過組織的 SSO 登入。配置說明參見網域名稱驗證。

步驟 2：建立 SSO 配置

管理員前往 組織設定 > 安全與身份。
根據你的 IDP 選擇 SAML 設定 或 OIDC 設定。

SAML

為你的組織建立 SAML 配置。系統將自動產生 SP 的認證和密鑰。初始化後，Qoder 將自動產生以下資訊供你查看，你在後續配置身份供應商（IDP）時將需要使用：

SP 實體 ID (SP Entity ID)
SP 中繼資料 URL (SP Metadata URL)
SP ACS (斷言消費者服務) URL
SP 認證和私密金鑰

產生的 SP 資訊樣本：

欄位	樣本值
SP 實體 ID	`https://qoder.com/saml/metadata/{org_id}`
SP 中繼資料 URL	`https://qoder.com/saml/metadata/{org_id}`
SP ACS URL	`https://qoder.com/sso/callback/saml/{org_id}`

OIDC

為你的組織建立 OIDC 配置。系統將自動產生回調地址（Redirect URI）和登入入口 URL，你在後續 IDP 側註冊 OAuth 2.0/OIDC 應用時將需要使用。產生的 SP 資訊樣本：

欄位	樣本值
Redirect URI (回調地址)	`https://qoder.com.cn/sso/callback/oidc/{org_id}`
登入入口 URL (Login URL)	`https://qoder.com.cn/sso/login/oidc/{org_id}`

請前往 IDP 控制台建立 OAuth 2.0 / OIDC 應用，將上述 Redirect URI 添加到應用允許的回調地址清單中。建立完成後，IDP 會頒發 Client ID 與 Client Secret，你將在步驟 3 中使用。

步驟 3：配置身份供應商（IDP）

SAML

你可以使用以下兩種方法來配置 SAML IDP：

方法 A：自動設定 (推薦)

如果你的 IDP 提供中繼資料 URL，請使用此方法進行自動設定：

在 SAML 配置頁面，找到 IDP 中繼資料配置 (Identity Provider Metadata Configuration) 部分。
選擇 中繼資料 URL (Import from URL) 配置模式。
輸入你的 IDP 中繼資料 URL (例如，https://your-idp.example.com/app/metadata)。
點擊儲存。

系統將自動擷取並解析以下資訊：

IDP 實體 ID
SSO URL
簽署憑證

方法 B：手動設定

如果你的 IDP 不提供中繼資料 URL，請按以下步驟手動設定設定：

在 SAML 配置頁面，選擇 手動設定 (Manual Configuration) 模式。
填寫以下欄位：
- IDP 實體 ID (IDP Entity ID)： 身份供應商的實體標識符。
- IDP SSO URL： SSO 登入端點 URL。
- IDP 密鑰憑證 (IDP Public Certificate)： PEM 格式的簽署憑證（可選，但推薦）。
點擊儲存。

OIDC

你可以使用以下兩種方法來配置 OIDC IDP：

方法 A：Issuer URL 自動探索 (推薦)

如果你的 IDP 符合 OpenID Connect Discovery 規範（即暴露 /.well-known/openid-configuration 端點），請使用此方法：

在 OIDC 配置頁面，選擇 Issuer URL 自動探索 配置模式。
填寫以下欄位：
- Issuer URL： IDP 的簽發者地址（例如 https://login.company.com、https://oauth.aliyun.com、https://your-tenant.authing.cn/oidc）。
- Client ID： IDP 中為 Qoder 應用頒發的用戶端識別碼。
- Client Secret： IDP 中為 Qoder 應用頒發的用戶端密鑰。
- Scopes（可選）：請求的許可權範圍，預設包含 openid，推薦使用 openid email profile。
點擊儲存。

系統將自動從 {Issuer URL}/.well-known/openid-configuration 擷取並解析：

Authorization Endpoint
Token Endpoint
UserInfo Endpoint
JWKS URL（用於驗證 ID Token 簽名）
支援的簽名演算法

方法 B：手動設定

如果你的 IDP 不支援 Discovery，請手動填寫：

Issuer URL、Client ID、Client Secret、Scopes
JWKS URL： JSON Web Key Set URL，用於驗證 ID Token 簽名。
End Session URL（可選）：登出時重新導向到 IDP 的會話結束端點。

openid 是 OIDC 協議的必選 Scope，如果未填寫系統會自動補齊。

步驟 4：配置身份供應商（IDP）

SAML

你可以使用以下兩種方法來配置 SAML IDP：

方法 A：自動設定 (推薦)

如果你的 IDP 提供中繼資料 URL，請使用此方法進行自動設定：

在 SAML 配置頁面，找到 IDP 中繼資料配置 (Identity Provider Metadata Configuration) 部分。
選擇 中繼資料 URL (Import from URL) 配置模式。
輸入你的 IDP 中繼資料 URL (例如，https://your-idp.example.com/app/metadata)。
點擊儲存。

系統將自動擷取並解析以下資訊：

IDP 實體 ID
SSO URL
簽署憑證

方法 B：手動設定

如果你的 IDP 不提供中繼資料 URL，請按以下步驟手動設定設定：

在 SAML 配置頁面，選擇 手動設定 (Manual Configuration) 模式。
填寫以下欄位：
- IDP 實體 ID (IDP Entity ID)： 身份供應商的實體標識符。
- IDP SSO URL： SSO 登入端點 URL。
- IDP 密鑰憑證 (IDP Public Certificate)： PEM 格式的簽署憑證（可選，但推薦）。
點擊儲存。

OIDC

在 OIDC 配置頁面，滾動到 屬性對應 (Attribute Mapping) 部分。
配置 OIDC UserInfo 中的 Claim 與系統欄位的映射：
- Email Claim： 使用者郵箱對應的 Claim 名，通常為 email。（必填）
- Name Claim： 使用者顯示名稱對應的 Claim 名，通常為 name 或 nickname。
- Open ID Claim： 使用者唯一標識 Claim，通常為 sub，也可使用 email。
點擊儲存。

Email 必填： 如果 IDP 返回的 UserInfo 中未包含有效 Email，認證將失敗。請確保你在 IDP 側已將 email Scope 授權給 Qoder 應用。

步驟 5：測試組態

在啟用前，請先測試 SSO 配置，以確保所有設定均已正確無誤：

在 SSO 配置頁面，點擊 測試組態 (Test SSO) 按鈕。
系統將運行一系列驗證檢查（認證/簽名、中繼資料端點、Discovery 文檔、屬性對應等）。
查看測試結果。

步驟 6：啟用 SSO

測試通過後，即可啟用 SSO：

在 SSO 配置頁面，確保所有測試檢查均已通過。
點擊 啟用 SSO 開關。
在彈出的對話方塊中確認資訊後啟用。

啟用後：

SSO 的狀態將變為已啟用。
組織成員現可使用 SAML 或 OIDC SSO 登入。
符合已驗證郵箱網域名稱的使用者，在登入頁輸入郵箱後將被自動導向組織的 SSO 登入。

建議啟用 SSO 後，當前管理員不要立即登出，另使用一個符合網域名稱的使用者嘗試 SSO 登入進行驗證，確保如 SSO 配置異常管理員有許可權可以修改調整。