Ctrlk
註冊/登入
For the complete documentation index, see llms.txt. This page is also available as Markdown.

SAML SSO 單一登入整合

SAML SSO 單一登入整合：IdP 與 SP 的架構、Email 正規化、帳號自動建立與衝突處理、配置步驟、限制與疑難排解。

本文件說明 MaiAgent 平台作為 SAML 2.0 服務提供者（SP）的技術規格：登入流程、讀取的使用者屬性、帳號建立與比對規則，以及設定時要準備的資訊。後台操作畫面與 Microsoft Entra ID 的逐步設定，請見使用者手冊「SAML 整合」。

1. 什麼是 SAML SSO？

SAML (Security Assertion Markup Language) 是一個基於 XML 的開放標準,用於在身分提供者 (Identity Provider, IdP) 和服務提供者 (Service Provider, SP) 之間交換身分驗證和授權資料。

SAML SSO 的導入效益與適用情境，請見使用者手冊「第三方登入（SSO）」。

2. MaiAgent SAML SSO 架構

2.1 關鍵元件說明

  • Service Provider (SP): MaiAgent 平台作為服務提供者,接收和驗證 SAML 回應

  • Identity Provider (IdP): 企業的身分驗證系統,如 Azure AD、Okta、Google Workspace

  • SAML Assertion: IdP 簽署的 XML 文件,包含使用者的身分和屬性資訊

  • IdP 設定來源: MaiAgent 可從 IdP Metadata URL 自動讀取 IdP 設定，或由管理員手動填入 Entity ID、SSO URL 與 X.509 憑證（見 5.2 節）

2.2 使用者屬性映射

MaiAgent 只讀取 Email 與顯示名稱兩項屬性，對應規則是固定的，無法在後台自訂；部門、職稱、群組、角色等其他屬性不會被讀取。

用途
MaiAgent 讀取的屬性（依序）
說明

Email（必要）

1. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name（Microsoft Entra ID、ADFS 的預設輸出） 2. urn:oid:0.9.2342.19200300.100.1.3 或 http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress 3. 格式為 urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress 的 NameID

轉為小寫後作為帳號識別。三者都沒有時登入失敗

顯示名稱

http://schemas.microsoft.com/identity/claims/displayname

只在首次登入、建立帳號時寫入。未提供時，改用 Email @ 前的文字或 IdP 送出的姓名屬性

請在 IdP 端確認上表至少一種 Email 屬性有送出。

3. Email 正規化處理

3.1 為何需要 Email 正規化？

Email 地址在技術上是不區分大小寫的(RFC 5321),但在不同系統中可能以不同大小寫形式出現:

  • IdP 回傳: John.Doe@Company.com

  • 使用者手動輸入: john.doe@company.com

  • API 呼叫: JOHN.DOE@COMPANY.COM

如果不進行正規化處理,可能導致:

  • 同一個使用者被建立多個帳號

  • 權限判斷錯誤

  • 資料不一致

3.2 MaiAgent 的正規化策略

系統會將 Email 統一轉為小寫，確保帳號比對的一致性。

正規化時機:

  1. SAML 回應解析時: 從 IdP 接收到使用者 Email 後立即轉為小寫

  2. 帳號查詢時: 以小寫 Email 查找現有使用者

  3. 資料庫儲存時: 使用者帳號儲存時，Email 一律存成小寫

4. 帳號自動建立與帳號衝突處理

4.1 自動建立帳號流程

當使用者首次透過 SAML SSO 登入時,MaiAgent 會自動建立帳號:

自動建立時的設定:

  • 顯示名稱: 依 2.2 節的規則取得

  • 登入來源: 設為此 SAML 認證來源

  • 組織歸屬: 若此認證來源設有預設組織，帳號會自動加入該組織成為成員

  • 角色: SAML 不會傳遞或同步角色，成員的角色由組織管理員在 MaiAgent 後台指派

4.2 帳號已存在的處理

  • Email 已註冊: 如果使用者先前已用相同 Email(小寫)註冊,則直接登入現有帳號；該帳號的登入來源會改為此 SAML 認證來源，並加入此認證來源的預設組織

  • 不寄送通知信: 偵測到既有帳號時直接完成關聯，不會寄信通知使用者

  • 防止重複建立: 透過資料庫唯一約束(Unique Constraint)確保同一 Email 不會建立多個帳號

4.3 安全性考量

  • Email 驗證: 信任 IdP 提供的 Email,因其已通過企業身分驗證

  • SAML 簽章驗證: 嚴格驗證 SAML Response 的數位簽章,防止偽造

  • 時間戳檢查: 確保 SAML Assertion 未過期

  • 請由 MaiAgent 發起登入: 建議從 MaiAgent 登入頁發起 SSO 登入；由 IdP 入口直接發起（IdP-initiated）的登入可能無法完成，如有需求請洽 MaiAgent 窗口

5. SAML SSO 配置步驟

5.1 在 IdP 端配置

企業 IT 管理員需要在 IdP (如 Okta、Azure AD) 中:

  1. 建立新的 SAML 應用程式

  2. 填入 MaiAgent 的 SP 資訊：

    • Entity ID（Audience URI）：{MaiAgent 後端網址}/accounts/saml/{認證來源名稱}/metadata/

    • ACS URL（Reply URL）：{MaiAgent 後端網址}/accounts/saml/{認證來源名稱}/acs/

    兩個網址在 MaiAgent 端儲存 SAML 設定後，會顯示在設定頁的「Service Provider 資訊」區塊，可直接複製。

    兩個值的角色不同：Entity ID 是 MaiAgent 這個 SP 的識別名稱，IdP 用它判斷 Assertion 是發給誰（Audience）；ACS URL（Assertion Consumer Service）是使用者在 IdP 登入成功後，IdP 把簽章過的 SAML Response 以瀏覽器 POST 送回的 MaiAgent 端點，MaiAgent 在這裡驗證簽章、讀取 Email 屬性並完成登入。IdP 只會把回應送到預先登記的 ACS URL，所以必須與 MaiAgent 顯示的值完全一致（含結尾的 /）；填錯時 IdP 會拒絕或 MaiAgent 收不到回應。它和 MaiAgent 的登入入口（/auth/saml/{認證來源名稱}/login/，使用者點「SSO 登入」時被導向的網址）是兩個不同的端點。

  3. 確認送出 Email 屬性：送出 2.2 節列出的任一種 Email 屬性；如要顯示姓名，另送 displayname

  4. 取得 IdP 設定：IdP Metadata URL，或 IdP Entity ID、SSO URL 與 X.509 憑證

5.2 在 MaiAgent 端配置

MaiAgent 管理員在組織設定的 第三方登入設定 選擇 SAML，填寫 認證來源名稱（會組進 SP 網址），再從以下兩種模式擇一提供 IdP 設定，兩種不能同時填：

模式
要填的欄位
說明

A：Metadata URL

IdP Metadata URL

儲存時系統會下載並解析 metadata，自動取得 Entity ID、SSO URL 與憑證。MaiAgent 伺服器必須連得到這個網址，連不到或格式錯誤時無法儲存

B：手動設定

IdP Entity ID、IdP SSO URL、IdP X.509 憑證

三個欄位都要填。憑證填 PEM 中 BEGIN CERTIFICATE／END CERTIFICATE 之間的 base64 內容。適用於 Google Workspace 等無法提供 Metadata URL、只能下載 metadata 檔的 IdP

選填 電子郵件網域：設定後，使用此網域信箱的成員在登入頁輸入信箱時，會自動被導向此 SAML 登入。

MaiAgent 沒有「上傳 IdP Metadata XML 檔」的欄位；手上只有 metadata 檔時，請從檔案中取出 Entity ID、SSO URL 與憑證，改用模式 B。屬性對應也沒有設定欄位，規則見 2.2 節。

儲存後，頁面會顯示 SP 資訊與提供給成員使用的登入連結。

5.3 測試與驗證

配置完成後,建議進行以下測試:

  • 首次登入測試: 確認自動建立帳號功能正常

  • 重複登入測試: 確認使用現有帳號登入

  • Email 大小寫測試: 驗證不同大小寫形式的 Email 都能正確識別

  • 登出測試: 確認 Single Logout (SLO) 功能正常

6. 限制與注意事項

  • 屬性對應固定: 只讀取 Email 與顯示名稱，無法自訂對應，也不讀取群組或部門

  • 姓名不同步: 顯示名稱只在首次登入時寫入，之後在 IdP 端修改不會同步到 MaiAgent

  • 角色不同步: SAML 不會帶入角色。需要依 IdP 群組自動開通成員與角色時，請改用 SCIM 等成員開通方式

  • 離職停用: SSO 只在登入時開通帳號，在 IdP 停用使用者不會停用 MaiAgent 成員；離職者請用 SCIM 或在後台停用

  • IdP 憑證更換: Metadata URL 模式只在儲存時讀取 metadata。IdP 更換簽章憑證後，請回到設定頁重新儲存（模式 A）或更新 X.509 憑證欄位（模式 B），否則簽章驗證會失敗

7. 疑難排解

7.1 常見問題

問題
可能原因
解決方式

無法登入

SAML 簽章驗證失敗

確認 IdP 的憑證未過期；若 IdP 已更換憑證，依第 6 節重新儲存或更新憑證

建立重複帳號

Email 大小寫不一致

確保系統已套用 Email 正規化修正

屬性缺失

IdP 未傳送 Email 屬性

登入會被導回並帶 error=email_not_found；請在 IdP 送出 2.2 節列出的任一種 Email 屬性

從 IdP 入口點應用程式無法登入

登入由 IdP 主動發起，不是由 MaiAgent 發起

在 IdP 將應用程式的登入 URL（Sign-on URL）設為 MaiAgent 的登入連結，讓登入由 MaiAgent 發起

時間戳錯誤

伺服器時間不同步

確保 SP 和 IdP 的系統時間一致(建議使用 NTP)

7.2 除錯工具

  • SAML-tracer: 瀏覽器擴充功能,可捕捉和解析 SAML 訊息

  • MaiAgent 日誌: 查看詳細的 SAML 處理日誌

  • IdP 管理介面: 檢查 IdP 端的錯誤日誌和使用者屬性

8. 相關文檔

參考連結

上一頁SSO 與身分整合總覽
下一頁MaiAgent 作為 OAuth 授權伺服器

最後更新於

這有幫助嗎？