search
註冊/登入

SAML SSO 單一登入整合

本文件說明 MaiAgent 平台如何整合 SAML 2.0 協定,實現企業級的單一登入(Single Sign-On, SSO)功能,並確保使用者身份驗證的安全性與正確性。

hashtag
1. 什麼是 SAML SSO？

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

hashtag
1.1 SAML SSO 的核心優勢

考量面向
傳統多重登入方案
SAML SSO 方案

使用者體驗

每個系統都需要單獨登入,密碼難以管理

一次登入即可存取多個系統,提升工作效率

安全性

密碼分散儲存在多個系統,增加洩漏風險

密碼僅儲存在企業的 IdP,集中管理更安全

帳號管理

員工離職需逐一停用各系統帳號

在 IdP 停用帳號即可統一撤銷所有系統存取權

合規性

難以統一稽核和管理存取記錄

集中化的身份管理符合企業資安合規要求

hashtag
1.2 常見應用場景

  • 企業內部系統整合: 員工使用公司的 Active Directory 或 Okta 登入 MaiAgent

  • 教育機構: 學生和教職員使用學校的 IdP 存取 AI 學習助理

  • 多租戶 SaaS: 不同企業客戶使用各自的 IdP 登入 MaiAgent 平台

  • 合作夥伴協作: 允許外部合作夥伴使用自己的企業帳號存取特定資源

hashtag
2. MaiAgent SAML SSO 架構

spinner

hashtag
2.1 關鍵元件說明

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

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

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

  • Metadata Exchange: SP 和 IdP 透過 XML metadata 交換配置資訊

hashtag
2.2 使用者屬性映射

MaiAgent 從 SAML Assertion 中提取以下使用者屬性:

  • Email (必要): 作為使用者的唯一識別,系統會自動轉為小寫以確保一致性

  • 名稱: 使用者的顯示名稱

  • 組織資訊: 部門、職稱等(依 IdP 配置而定)

  • 群組/角色: 用於權限管理和存取控制

hashtag
3. Email 正規化處理

hashtag
3.1 為何需要 Email 正規化？

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

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

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

  • 權限判斷錯誤

  • 資料不一致

hashtag
3.2 MaiAgent 的正規化策略

MaiAgent 在 SAML SSO 整合中實作了以下 Email 正規化措施:

系統會自動將 Email 去除前後空白並統一轉為小寫格式，確保帳號比對的一致性。

正規化時機:

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

  2. 帳號建立時: 建立新使用者帳號前確保 Email 為小寫

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

  4. 資料庫儲存時: 所有儲存的 Email 都保持小寫格式

hashtag
3.3 向下相容性處理

對於在正規化機制實作前建立的帳號,MaiAgent 採用以下策略:

  • 自動遷移: 系統會自動將現有帳號的 Email 轉為小寫

  • 重複檢測: 在轉換過程中檢測是否存在重複帳號

  • 衝突解決: 若發現衝突,保留最早建立的帳號,並合併資料

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

hashtag
4.1 自動建立帳號流程

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

spinner

自動建立時的預設設定:

  • 顯示名稱: 從 SAML Assertion 中的 name 屬性提取

  • 預設權限: 依據組織設定指派基本權限

  • 組織歸屬: 根據 Email domain 或 IdP 配置決定

hashtag
4.2 帳號已存在的處理

MaiAgent 實作了智慧型的帳號衝突偵測與處理機制:

  • Email 已註冊: 如果使用者先前已用相同 Email(小寫)註冊,則直接登入現有帳號

  • 發送通知郵件: 當偵測到已存在的帳號時,發送郵件通知使用者

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

hashtag
4.3 安全性考量

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

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

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

  • 重放攻擊防護: 記錄已使用的 SAML Response ID,防止重複使用

hashtag
5. SAML SSO 配置步驟

hashtag
5.1 在 IdP 端配置

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

  1. 建立新的 SAML 應用程式

  2. 設定 MaiAgent 的 ACS URL (Assertion Consumer Service URL)

  3. 配置使用者屬性映射,確保包含 Email

  4. 下載 IdP Metadata XML,提供給 MaiAgent

hashtag
5.2 在 MaiAgent 端配置

MaiAgent 管理員需要:

  1. 上傳 IdP Metadata XML 到 MaiAgent 後台

  2. 設定 Entity ID,識別此 SAML 整合

  3. 配置屬性映射規則,如 Email、姓名等欄位對應

  4. 啟用 SAML SSO,並測試登入流程

hashtag
5.3 測試與驗證

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

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

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

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

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

hashtag
6. MaiAgent SAML SSO 的技術優勢

hashtag
6.1 安全性優勢

  • 企業級身份驗證: 利用企業現有的身份管理系統,確保驗證標準一致

  • 密碼不經過 MaiAgent: 使用者密碼僅在企業 IdP 中驗證,降低洩漏風險

  • 集中化存取控制: IT 管理員可在 IdP 統一管理所有應用程式的存取權限

  • 強制多因素驗證: 若 IdP 啟用 MFA,使用者登入 MaiAgent 時也會要求 MFA

hashtag
6.2 管理效率優勢

  • 自動帳號建立: 減少手動建立帳號的作業負擔

  • 自動停用帳號: 員工離職時在 IdP 停用帳號,MaiAgent 存取權也會立即失效

  • 屬性同步: 使用者的姓名、部門等資訊變更時自動同步

  • 稽核記錄: 所有登入活動都有完整記錄,便於安全稽核

hashtag
6.3 使用者體驗優勢

  • 無縫登入: 若使用者已登入企業系統,存取 MaiAgent 時可能無需再次輸入密碼

  • 統一登入介面: 使用熟悉的企業登入頁面,無需記憶額外密碼

  • 行動裝置友善: 支援行動裝置上的 SSO 體驗

hashtag
7. 疑難排解

hashtag
7.1 常見問題

問題
可能原因
解決方式

無法登入

SAML 簽章驗證失敗

確認 IdP 的憑證未過期,且 Metadata 為最新版本

建立重複帳號

Email 大小寫不一致

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

屬性缺失

IdP 未傳送必要屬性

檢查 IdP 的屬性映射配置,確保包含 Email

時間戳錯誤

伺服器時間不同步

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

hashtag
7.2 除錯工具

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

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

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

hashtag
8. 相關文檔

hashtag
參考連結

PreviousOAuth 2.0 整合與 Token 自動刷新機制NextLiveKit 語音代理整合架構

Last updated

Was this helpful?