# SAML SSO 單一登入整合

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

## 1. 什麼是 SAML SSO？

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

### 1.1 SAML SSO 的核心優勢

| 考量面向      | 傳統多重登入方案           | SAML SSO 方案             |
| --------- | ------------------ | ----------------------- |
| **使用者體驗** | 每個系統都需要單獨登入,密碼難以管理 | 一次登入即可存取多個系統,提升工作效率     |
| **安全性**   | 密碼分散儲存在多個系統,增加洩漏風險 | 密碼僅儲存在企業的 IdP,集中管理更安全   |
| **帳號管理**  | 員工離職需逐一停用各系統帳號     | 在 IdP 停用帳號即可統一撤銷所有系統存取權 |
| **合規性**   | 難以統一稽核和管理存取記錄      | 集中化的身份管理符合企業資安合規要求      |

### 1.2 常見應用場景

* **企業內部系統整合**: 員工使用公司的 Active Directory 或 Okta 登入 MaiAgent
* **教育機構**: 學生和教職員使用學校的 IdP 存取 AI 學習助理
* **多租戶 SaaS**: 不同企業客戶使用各自的 IdP 登入 MaiAgent 平台
* **合作夥伴協作**: 允許外部合作夥伴使用自己的企業帳號存取特定資源

***

## 2. MaiAgent SAML SSO 架構

{% @mermaid/diagram content="sequenceDiagram
participant User as 使用者
participant Browser as 瀏覽器
participant MaiAgent as MaiAgent (SP)
participant IdP as 企業 IdP

```
User->>Browser: 訪問 MaiAgent
Browser->>MaiAgent: 請求存取
MaiAgent->>Browser: 重導向至 IdP<br/>(SAML AuthnRequest)
Browser->>IdP: 轉發認證請求

IdP->>User: 顯示登入頁面
User->>IdP: 輸入企業帳號密碼
IdP->>IdP: 驗證使用者身份

IdP->>Browser: 返回 SAML Response<br/>(包含使用者屬性)
Browser->>MaiAgent: POST SAML Response

MaiAgent->>MaiAgent: 驗證 SAML 簽章
MaiAgent->>MaiAgent: 解析使用者屬性<br/>(Email、姓名等)
MaiAgent->>MaiAgent: 正規化 Email<br/>(轉為小寫)

alt 使用者已存在
    MaiAgent->>MaiAgent: 建立登入會話
else 使用者不存在
    MaiAgent->>MaiAgent: 自動建立帳號
end

MaiAgent->>Browser: 重導向至應用首頁
Browser->>User: 顯示 MaiAgent 介面" %}
```

### 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 交換配置資訊

### 2.2 使用者屬性映射

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

* **Email (必要)**: 作為使用者的唯一識別,系統會自動轉為小寫以確保一致性
* **名稱**: 使用者的顯示名稱
* **組織資訊**: 部門、職稱等(依 IdP 配置而定)
* **群組/角色**: 用於權限管理和存取控制

***

## 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 的正規化策略

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

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

**正規化時機**:

1. **SAML 回應解析時**: 從 IdP 接收到使用者 Email 後立即轉為小寫
2. **帳號建立時**: 建立新使用者帳號前確保 Email 為小寫
3. **帳號查詢時**: 查找現有使用者時也使用小寫 Email
4. **資料庫儲存時**: 所有儲存的 Email 都保持小寫格式

### 3.3 向下相容性處理

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

* **自動遷移**: 系統會自動將現有帳號的 Email 轉為小寫
* **重複檢測**: 在轉換過程中檢測是否存在重複帳號
* **衝突解決**: 若發現衝突,保留最早建立的帳號,並合併資料

***

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

### 4.1 自動建立帳號流程

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

{% @mermaid/diagram content="flowchart TD
A\["接收 SAML Response"] --> B\["解析使用者 Email"]
B --> C\["Email 轉為小寫"]
C --> D{"帳號是否存在?"}
D -- "是" --> E\["載入現有帳號"]
D -- "否" --> F\["自動建立新帳號"]
F --> G\["設定預設權限"]
G --> H\["建立登入會話"]
E --> H
H --> I\["重導向至首頁"]" %}

**自動建立時的預設設定**:

* **顯示名稱**: 從 SAML Assertion 中的 name 屬性提取
* **預設權限**: 依據組織設定指派基本權限
* **組織歸屬**: 根據 Email domain 或 IdP 配置決定

### 4.2 帳號已存在的處理

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

* **Email 已註冊**: 如果使用者先前已用相同 Email(小寫)註冊,則直接登入現有帳號
* **發送通知郵件**: 當偵測到已存在的帳號時,發送郵件通知使用者
* **防止重複建立**: 透過資料庫唯一約束(Unique Constraint)確保同一 Email 不會建立多個帳號

### 4.3 安全性考量

* **Email 驗證**: 信任 IdP 提供的 Email,因其已通過企業身份驗證
* **SAML 簽章驗證**: 嚴格驗證 SAML Response 的數位簽章,防止偽造
* **時間戳檢查**: 確保 SAML Assertion 未過期
* **重放攻擊防護**: 記錄已使用的 SAML Response ID,防止重複使用

***

## 5. SAML SSO 配置步驟

### 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

### 5.2 在 MaiAgent 端配置

MaiAgent 管理員需要:

1. **上傳 IdP Metadata XML** 到 MaiAgent 後台
2. **設定 Entity ID**,識別此 SAML 整合
3. **配置屬性映射規則**,如 Email、姓名等欄位對應
4. **啟用 SAML SSO**,並測試登入流程

### 5.3 測試與驗證

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

* **首次登入測試**: 確認自動建立帳號功能正常
* **重複登入測試**: 確認使用現有帳號登入
* **Email 大小寫測試**: 驗證不同大小寫形式的 Email 都能正確識別
* **登出測試**: 確認 Single Logout (SLO) 功能正常

***

## 6. MaiAgent SAML SSO 的技術優勢

### 6.1 安全性優勢

* **企業級身份驗證**: 利用企業現有的身份管理系統,確保驗證標準一致
* **密碼不經過 MaiAgent**: 使用者密碼僅在企業 IdP 中驗證,降低洩漏風險
* **集中化存取控制**: IT 管理員可在 IdP 統一管理所有應用程式的存取權限
* **強制多因素驗證**: 若 IdP 啟用 MFA,使用者登入 MaiAgent 時也會要求 MFA

### 6.2 管理效率優勢

* **自動帳號建立**: 減少手動建立帳號的作業負擔
* **自動停用帳號**: 員工離職時在 IdP 停用帳號,MaiAgent 存取權也會立即失效
* **屬性同步**: 使用者的姓名、部門等資訊變更時自動同步
* **稽核記錄**: 所有登入活動都有完整記錄,便於安全稽核

### 6.3 使用者體驗優勢

* **無縫登入**: 若使用者已登入企業系統,存取 MaiAgent 時可能無需再次輸入密碼
* **統一登入介面**: 使用熟悉的企業登入頁面,無需記憶額外密碼
* **行動裝置友善**: 支援行動裝置上的 SSO 體驗

***

## 7. 疑難排解

### 7.1 常見問題

| 問題         | 可能原因         | 解決方式                           |
| ---------- | ------------ | ------------------------------ |
| **無法登入**   | SAML 簽章驗證失敗  | 確認 IdP 的憑證未過期,且 Metadata 為最新版本 |
| **建立重複帳號** | Email 大小寫不一致 | 確保系統已套用 Email 正規化修正            |
| **屬性缺失**   | IdP 未傳送必要屬性  | 檢查 IdP 的屬性映射配置,確保包含 Email      |
| **時間戳錯誤**  | 伺服器時間不同步     | 確保 SP 和 IdP 的系統時間一致(建議使用 NTP)  |

### 7.2 除錯工具

* **SAML-tracer**: 瀏覽器擴充功能,可捕捉和解析 SAML 訊息
* **MaiAgent 日誌**: 查看詳細的 SAML 處理日誌
* **IdP 管理介面**: 檢查 IdP 端的錯誤日誌和使用者屬性

***

## 8. 相關文檔

* [組織與成員管理](https://docs.maiagent.ai/org/role-permission) - 了解 SAML 使用者的權限管理
* [第三方登入(SSO)](https://docs.maiagent.ai/org/sso) - 使用者指南中的 SSO 配置說明

### 參考連結

* [SAML 2.0 Technical Overview](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html)
* [SAML Security Best Practices](https://www.oasis-open.org/committees/download.php/56776/sstc-saml-sec-consider-2.0-os.pdf)