SSO 設定參考

單一登入所有可設定的項目，全都集中在這裡。這些值存放在 global.db 的 sso_connections 資料列中（依設計屬於伺服器層級），可透過 設定 → 伺服器 → 單一登入 或 sso.* RPC 操作來編輯。已儲存的資料列 是唯一的真實來源——沒有 CC_SAML_* / CC_OIDC_* 這條環境變數路徑 （一個能從兩個地方出現的連線，就是設定畫面可能與之不一致的那種連線）。

連線欄位

欄位	適用於	預設值	意義
enabled	兩者	關閉	登入可以使用這個連線
idpMetadataXml	SAML	—	IdP 的 EntityDescriptor XML（啟用時必須提供）
spEntityId	SAML	<origin>/saml	我們的實體 ID；當來源會變動時會予以釘選
emailAttribute	SAML	email	承載電子郵件的屬性；若無，則退回使用電子郵件形式的 NameID
displayNameAttribute	SAML	displayName	顯示名稱屬性
groupsAttribute	SAML	groups	群組名稱屬性
clockSkewSeconds	SAML	90	有效期間驗證容許的時鐘偏差
allowIdpInitiated	SAML	關閉	接受未經請求的回應（沒有 InResponseTo）
wantResponseSigned	SAML	關閉	要求 Response 根層級的簽章（判斷提示簽章一律必要）
issuer	OIDC	—	簽發者基準 URL（啟用時必須提供）
clientId	OIDC	—	公開用戶端 id（啟用時必須提供）
clientSecret	OIDC	—	僅限機密式用戶端；儲存在權限 0600 的機密檔案中，絕不會存進資料庫——透過 RPC 只能寫入（sso.getConfig 會回報 clientSecretPresent）
groupsClaim	OIDC	groups	承載群組名稱的宣告
defaultRole	兩者	member	沒有任何群組對應時的角色——絕不會是 owner
groupRoleMap	兩者	{}	群組 → 角色；儲存時會拒絕擁有者的對應
autoMember	兩者	開啟	首次登入時自動將使用者加入每個工作區
allowJit	兩者	開啟	登入時佈建未知的使用者

行程設定

SSO 連線不會從環境植入。剩下的一個行程旗標談的是瀏覽器交付，而不是 連線資料列：

變數／旗標	意義
--web-client-url / CC_SERVER_WEB_CLIENT_URL	SSO 回呼會把瀏覽器重導到的來源（憑證隨 URL 片段傳遞）。未設定時，交付會維持在同源。

簽發者 URL 本身必須是 https（只有回送位址的簽發者 localhost、 127.0.0.1 與 ::1 才接受 http）。

HTTP 端點

端點	驗證	用途
GET /saml/login?relay=…	無（重新導向）	開始由 SP 發起的登入；relay=desktop 會交付給應用程式，relay=web-popup 會對等待中的連線分頁發出 postMessage（該分頁會宣告自己的 client_origin，只有在來源允許清單信任它時才會被採用）
POST /saml/acs	無（IdP POST）	判斷提示取用端——驗證、佈建、簽發
GET /saml/metadata	無	我們的 SP EntityDescriptor
GET /oidc/login?relay=… / GET /oidc/callback	無	OIDC 往返；relay=desktop 交付給應用程式，relay=web-popup 則交付給等待中的連線分頁（同樣的 client_origin 慣例）
GET /auth/providers	無，CORS *	連線畫面的探測：可用的 SSO 連線（id/kind/label）與 pairingEnabled
/scim/v2/Users…	Bearer（SCIM 權杖）	Users 的建立／取得／列出＋篩選／PUT／PATCH／DELETE
/scim/v2/Groups	Bearer	唯讀；群組推送依設計會回應 501
/scim/v2/ServiceProviderConfig	Bearer	能力文件

RPC 操作

所有 sso.* 操作都以伺服器為範圍，且僅限伺服器擁有者（這台安裝的 操作者，ServerAuthority.serverOwner）執行。只擁有一個工作區並不夠； 只有配對身分也永遠不會授予這些權限。

操作	用途
sso.getConfig	某種類型已儲存的連線
sso.saveConfig	驗證、保存並即時套用
sso.status	已啟用／已設定的旗標、SCIM 權杖是否存在、標準來源
sso.testConnection	在不用進行瀏覽器往返的情況下測試連線（SAML：剖析中繼資料＋建構 AuthnRequest；OIDC：簽發者探索），可選擇使用畫面上尚未儲存的值
sso.spMetadata	針對某個來源產生 SP EntityDescriptor
sso.setPairingEnabled	允許／禁止手動配對（邀請碼、配對金鑰）；在沒有可用的 SSO 連線時拒絕停用，可防止把自己鎖在外面
sso.sessionPolicy	讀取這台安裝的裝置憑證最長存續時間與閒置逾時（分鐘；0 = 未設定）
sso.setSessionPolicy	設定這些界限；在裝置檢查時強制執行，不會向用戶端公告
sso.scimRegenerateToken	產生並回傳 SCIM bearer 權杖（僅一次）

驗證錯誤碼

cc_saml_verify_response 的失敗會帶有穩定的錯誤碼：

錯誤碼	意義
signature	簽章缺少／不受信任／遭竄改，或使用了不允許的演算法／轉換
expired	落在 NotBefore/NotOnOrAfter 之外（超出偏差容許範圍）
audience	對象限制沒有指名我們
destination	回應的目的地不是我們的 ACS
request_match	InResponseTo 與任何待處理的要求都不相符，或在禁止未經請求時仍屬未經請求
issuer	簽發者不是設定的 IdP
recipient	主體確認的收件者不是我們的 ACS
malformed	XML／結構定義層級的失敗
status	IdP 回報的狀態不是 Success
invalid / internal	其他任何情況／接縫失效

資料庫表面

• sso_connections（global.db）——每種類型一列，依設計就是跨工作區。
• users.sso_subject 與 users.sso_issuer——供應商主體的釘選，透過部分 索引讓 (issuer, subject) 保持唯一。
• users.deactivated_at——SCIM 停用標記。
• SCIM bearer 權杖與 OIDC 用戶端密鑰存放在權限 0600 的機密檔案中，絕不會 存進資料庫。