# SAML 整合

SAML（Security Assertion Markup Language）是企業級應用廣泛採用的標準驗證協定。

**適用對象**：已建置 SAML 身分提供者的企業（如 Microsoft Entra ID / Azure AD、Okta、Google Workspace）

**主要優勢**：

* 業界標準協定，相容性高
* 支援完整的使用者屬性傳遞
* 可整合多因素驗證（MFA）
* 支援單一登出（Single Logout, SLO）

## 設定步驟 <a href="#setup-steps" id="setup-steps"></a>

### 1. 在 MaiAgent 後台填寫 IdP 資訊 <a href="#step-1-fill-idp-info" id="step-1-fill-idp-info"></a>

<figure><img src="/files/UkCEQ60u9EPB6pLESucu" alt="SAML 設定"><figcaption><p>SAML 認證設定：填寫 IdP 資訊後系統會自動產生 SP 資訊</p></figcaption></figure>

選擇 <mark style="color:blue;">SAML</mark> 認證類型後，需要填寫以下欄位：

| 欄位               | 必填 | 說明                             |
| ---------------- | -- | ------------------------------ |
| 認證來源名稱           | 是  | 用於產生 SP 端點 URL，例如 `my-company` |
| IdP Metadata URL | 是  | 身分提供者的中繼資料 URL                 |
| IdP Entity ID    | 是  | 身分提供者的實體識別碼                    |
| IdP SSO URL      | 是  | 身分提供者的單一登入端點 URL               |
| Email Domain     | 否  | 可選填企業 Email 網域                 |

### 2. 取得 SP（MaiAgent 端）資訊 <a href="#step-2-get-sp-info" id="step-2-get-sp-info"></a>

填寫認證來源名稱後，系統會自動產生以下 SP 資訊，顯示在設定頁面中：

| SP 欄位                  | 格式                                          | 說明          |
| ---------------------- | ------------------------------------------- | ----------- |
| Entity ID（實體識別碼）       | `https://{域名}/accounts/saml/{名稱}/metadata/` | 提供給 IdP 設定用 |
| ACS URL（判斷提示取用者服務 URL） | `https://{域名}/accounts/saml/{名稱}/acs/`      | 提供給 IdP 設定用 |
| Login URL（登入 URL）      | `https://{API 域名}/auth/saml/{名稱}/login/`    | SAML 登入入口   |

{% hint style="info" %}
SP 資訊區域提供 <mark style="color:blue;">複製</mark> 按鈕，方便您直接複製 URL 到 IdP 的設定介面。
{% endhint %}

### 3. 在身分提供者（IdP）設定 MaiAgent 應用程式 <a href="#step-3-configure-idp" id="step-3-configure-idp"></a>

以 **Microsoft Entra ID（Azure AD）** 為例：

1. 登入 [Azure Portal](https://portal.azure.com/) > <mark style="color:blue;">Microsoft Entra ID</mark> > <mark style="color:blue;">企業應用程式</mark>
2. 點擊 <mark style="color:blue;">新增應用程式</mark> > <mark style="color:blue;">建立您自己的應用程式</mark>
3. 選擇「**整合您在資源庫中找不到的其他任何應用程式（非資源庫）**」

<figure><img src="/files/rPKsxTTswW2TeSd3XtP8" alt="建立企業應用程式"><figcaption><p>在 Azure AD 中建立自訂企業應用程式</p></figcaption></figure>

4. 選取剛建立的企業應用程式

<figure><img src="/files/QikzBPppDEXdDxdqfHkM" alt="選取企業應用程式"><figcaption><p>選取指定的企業應用程式</p></figcaption></figure>

5. 進入企業應用程式，點選左側 <mark style="color:blue;">單一登入</mark> > <mark style="color:blue;">SAML</mark>

<figure><img src="/files/o4AyWZhlKkt5is2DSQdE" alt="選擇 SAML"><figcaption><p>選擇 SAML 作為單一登入方式</p></figcaption></figure>

6. 在 <mark style="color:blue;">基本 SAML 設定</mark> 區段填入 MaiAgent 的 SP 資訊：
   * **識別碼（實體識別碼）**：填入 MaiAgent 產生的 Entity ID
   * **回覆 URL（判斷提示取用者服務 URL）**：填入 MaiAgent 產生的 ACS URL

<figure><img src="/files/GzzndM7c9zfH8wAf5Qc7" alt="基本 SAML 設定"><figcaption><p>在基本 SAML 設定中填入 MaiAgent 的 Entity ID 和 ACS URL</p></figcaption></figure>

7. 儲存設定

### 4. 從 IdP 取得設定值並填回 MaiAgent <a href="#step-4-fill-idp-values-back" id="step-4-fill-idp-values-back"></a>

在 Azure AD 的 <mark style="color:blue;">設定 SAML 單一登入</mark> 頁面底部，找到以下資訊：

| Azure AD 欄位         | 對應 MaiAgent 欄位   |
| ------------------- | ---------------- |
| 應用程式同盟中繼資料 URL      | IdP Metadata URL |
| Microsoft Entra 識別碼 | IdP Entity ID    |
| 登入 URL              | IdP SSO URL      |

將這些值填入 MaiAgent 後台的 SAML 設定表單。

<figure><img src="/files/QzGeHBmpPq0jXgi5Jk8X" alt="IdP 資訊"><figcaption><p>從 Azure AD 取得 Microsoft Entra 識別碼、登入 URL 和中繼資料 URL</p></figcaption></figure>

### 5. 指派使用者與群組 <a href="#step-5-assign-users-groups" id="step-5-assign-users-groups"></a>

在 Azure AD 的企業應用程式中，點選 <mark style="color:blue;">使用者和群組</mark> > <mark style="color:blue;">新增使用者/群組</mark>，將需要存取 MaiAgent 的員工或群組加入。

<figure><img src="/files/g2oLDPVtuYDsqOSTb7gL" alt="新增使用者和群組"><figcaption><p>將需要存取 MaiAgent 的員工或群組加入企業應用程式</p></figcaption></figure>

### 6. 儲存並確認 <a href="#step-6-save-and-confirm" id="step-6-save-and-confirm"></a>

在 MaiAgent 後台點擊 <mark style="color:blue;">儲存</mark> 按鈕，系統會跳出確認視窗，提醒您：

* 切換認證類型後，員工登入方式將改變
* 現有使用者需使用新的 SSO 方式登入
* 請確保 IdP 端設定已完成

確認後即完成設定。

## SAML 屬性對應 <a href="#saml-attribute-mapping" id="saml-attribute-mapping"></a>

MaiAgent 會從 SAML 回應（SAML Response）中擷取以下屬性：

| SAML 屬性（Claim）                                               | MaiAgent 欄位 | 說明           |
| ------------------------------------------------------------ | ----------- | ------------ |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` | 使用者電子郵件     | 必要欄位，作為使用者識別 |
| `http://schemas.microsoft.com/identity/claims/displayname`   | 顯示名稱        | 顯示在介面中的使用者名稱 |

{% hint style="info" %}
如果 SAML 回應中未包含 displayname 屬性，系統會自動擷取 Email 的前綴（@ 前方的文字）作為顯示名稱。
{% endhint %}

## 其他 SAML IdP 設定 <a href="#other-saml-idp-settings" id="other-saml-idp-settings"></a>

MaiAgent 的 SAML 整合不限於 Microsoft Entra ID。只要您的身分提供者支援 SAML 2.0 標準協定，都可以完成整合。常見的 IdP 包括：

* **Okta**：在 Applications 中新增 SAML 2.0 App
* **Google Workspace**：在 Admin Console > Security > SSO 中設定
* **ADFS**：在 Relying Party Trusts 中新增

設定邏輯相同：將 MaiAgent 的 SP 資訊（Entity ID、ACS URL）填入 IdP，再將 IdP 的資訊（Metadata URL、Entity ID、SSO URL）填回 MaiAgent。

## SAML 安全特性 <a href="#saml-security-features" id="saml-security-features"></a>

* 支援 SAML 2.0 HTTP Redirect Binding
* Session Index 追蹤，確保登出操作的正確性
* NameID 格式使用 emailAddress，確保使用者識別一致性
* 登入 Cookie 設定：`Secure=True`、`SameSite=None`、`HttpOnly=True`，有效期 5 分鐘

## 設定欄位速查表 <a href="#settings-quick-reference" id="settings-quick-reference"></a>

| 欄位               | 必填 | 格式                   | 範例                                                                                        |
| ---------------- | -- | -------------------- | ----------------------------------------------------------------------------------------- |
| 認證來源名稱           | 是  | 小寫英數 + 連字號，max 31 字元 | `my-company`                                                                              |
| IdP Metadata URL | 是  | HTTPS URL            | `https://login.microsoftonline.com/.../federationmetadata/2007-06/federationmetadata.xml` |
| IdP Entity ID    | 是  | URI                  | `https://sts.windows.net/{tenant-id}/`                                                    |
| IdP SSO URL      | 是  | HTTPS URL            | `https://login.microsoftonline.com/{tenant-id}/saml2`                                     |
| Email Domain     | 否  | 網域格式                 | `company.com`                                                                             |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.maiagent.ai/org/sso/sso-saml.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.