> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/org/sso/sso-saml.md).

# SAML 整合

透過 SAML 2.0 協定整合 Azure AD、Okta、Google Workspace 等身分提供者

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

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

**主要優勢**：

* 業界標準協定，相容性高
* 以 Email 識別使用者，第一次登入時自動建立帳號（只讀取 Email 與顯示名稱，不讀取群組、部門等其他屬性）
* 可整合多因素驗證（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>

選擇 <mark style="color:blue;">SAML</mark> 認證類型後，先填 <mark style="color:blue;">認證來源名稱</mark>（用於產生 SP 端點 URL，例如 `my-company`），再從以下兩種模式**擇一**提供 IdP 設定。兩種模式不能同時填，同時填寫時無法儲存。

| 模式             | 要填的欄位                                                                                                                                            | 適用情境                                                                                                             |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| A：Metadata URL | <mark style="color:blue;">IdP Metadata URL</mark>                                                                                                | IdP 提供可公開讀取的中繼資料網址（例如 Microsoft Entra ID）。儲存時系統會下載並解析，自動取得 Entity ID、SSO URL 與憑證；MaiAgent 連不到這個網址時無法儲存           |
| B：手動設定         | <mark style="color:blue;">IdP Entity ID</mark>、<mark style="color:blue;">IdP SSO URL</mark>、<mark style="color:blue;">IdP X.509 憑證</mark>（三欄都要填） | IdP 只能下載 metadata 檔、沒有中繼資料網址（例如 Google Workspace）。憑證請貼 PEM 中 `BEGIN CERTIFICATE`／`END CERTIFICATE` 之間的 base64 內容 |

<mark style="color:blue;">電子郵件網域</mark> 為選填：設定後，使用這個網域信箱的成員在登入頁輸入信箱時，會自動被導向此 SAML 登入。

### 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 登入入口   |

三個值各有用途：Entity ID 是 MaiAgent 在 IdP 眼中的識別名稱；ACS URL（Assertion Consumer Service）是使用者在 IdP 登入成功後，IdP 把簽章過的 SAML 回應送回 MaiAgent 的網址，MaiAgent 在這裡驗證並完成登入，IdP 只會送到預先登記的網址，所以要原樣貼上（含結尾的 `/`）；Login URL 則是讓使用者開始 SSO 登入的入口，不用填進 IdP。技術說明見技術人員手冊 [SAML SSO 單一登入整合](https://docs.maiagent.ai/tech/identity-and-access/sso-overview/saml-sso)。

{% 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="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-0635609d8cfbc379308c3c09cf2d36b4bf5feccd%2Fsso-azure-01-create-enterprise-app.png?alt=media" alt="建立企業應用程式"><figcaption><p>在 Azure AD 中建立自訂企業應用程式</p></figcaption></figure>

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

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-7a355995c181ba03d74f063a04cf14f33a36c292%2Fsso-azure-02-select-enterprise-app.png?alt=media" alt="選取企業應用程式"><figcaption><p>選取指定的企業應用程式</p></figcaption></figure>

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

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-833772e0e67721e2176efc5172b2b60aea3a66ff%2Fsso-azure-03-sso-saml.png?alt=media" 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
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> 頁面底部，找到以下資訊，依[步驟 1](#step-1-fill-idp-info) 的模式擇一填回 MaiAgent 後台的 SAML 設定表單：

| 模式    | Azure AD 欄位               | 對應 MaiAgent 欄位   |
| ----- | ------------------------- | ---------------- |
| A（建議） | 應用程式同盟中繼資料 URL            | IdP Metadata URL |
| B     | Microsoft Entra 識別碼       | IdP Entity ID    |
| B     | 登入 URL                    | IdP SSO URL      |
| B     | SAML 憑證區段下載的「憑證 (Base64)」 | IdP X.509 憑證     |

使用模式 A 時只填 IdP Metadata URL，其他三欄留空。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-73eb33f62fc8b287844c32ca6fca687e5b511450%2Fsso-azure-05-idp-info.png?alt=media" 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="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-1712c334ffa9fc2b078865f6808ab6ae12aec56f%2Fsso-azure-06-add-users-groups.png?alt=media" 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> 按鈕，系統會跳出 <mark style="color:blue;">確認變更認證方式</mark> 視窗。請先確認 IdP 端設定已完成，再按 <mark style="color:blue;">確認變更</mark>，即完成設定。

{% hint style="warning" %}
啟用 SAML 後，已設定密碼的成員仍可用 Email＋密碼登入，系統不會自動停用密碼登入。要讓某位成員無法再用密碼存取組織，或讓離職停用自動化，請見[離職與停用成員](/org/sso.md#offboarding)。
{% endhint %}

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

MaiAgent 只從 SAML 回應讀取 **Email**（必要，作為帳號識別）與 **顯示名稱** 兩項屬性，對應規則固定、無法在後台自訂；群組、部門、職稱等其他屬性不會被讀取，也不會同步角色。

* **Email**：Microsoft Entra ID 與 ADFS 的預設輸出即可使用；其他 IdP 請確認有送出 Email 屬性，或把 NameID 格式設為 emailAddress。三種可接受的 Email 來源與讀取順序，見技術人員手冊 [SAML SSO 單一登入整合](https://docs.maiagent.ai/tech/identity-and-access/sso-overview/saml-sso) 第 2.2 節「使用者屬性映射」。
* **顯示名稱**：只在第一次登入、建立帳號時寫入；沒有送出顯示名稱時，改用 Email @ 前方的文字。之後在 IdP 端改名不會同步到 MaiAgent。

## 其他 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 中新增，完整步驟請參閱 [ADFS 整合](/org/sso/sso-saml/sso-saml-adfs.md)

設定邏輯相同：將 MaiAgent 的 SP 資訊（Entity ID、ACS URL）填入 IdP，再將 IdP 的資訊填回 MaiAgent：有 Metadata URL 就只填 Metadata URL（模式 A），沒有則填 Entity ID、SSO URL 與 X.509 憑證（模式 B）。

## 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 | 模式 A 必填 | HTTPS URL                                 | `https://login.microsoftonline.com/.../federationmetadata/2007-06/federationmetadata.xml` |
| IdP Entity ID    | 模式 B 必填 | URI                                       | `https://sts.windows.net/{tenant-id}/`                                                    |
| IdP SSO URL      | 模式 B 必填 | HTTPS URL                                 | `https://login.microsoftonline.com/{tenant-id}/saml2`                                     |
| IdP X.509 憑證     | 模式 B 必填 | PEM 中 BEGIN／END CERTIFICATE 之間的 base64 內容 | `MIID...`                                                                                 |
| 電子郵件網域           | 否       | 網域格式                                      | `company.com`                                                                             |

{% hint style="info" %}
模式 A 與模式 B 擇一填寫，不能同時提供。
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.