# 第三方登入（SSO）

企業單一登入（Single Sign-On, SSO）功能讓您的員工能夠使用公司既有的帳號系統登入 MaiAgent 平台，無需額外記憶新的帳號密碼。透過與企業身分驗證系統整合，員工只要登入一次公司系統，就能無縫存取 MaiAgent 的所有功能，大幅簡化登入流程並提升安全性。

{% hint style="info" %}
第三方登入（SSO）為 **企業版** 專屬功能。如需啟用，請聯繫 MaiAgent 業務團隊升級至企業方案。
{% endhint %}

## 使用場景

1. **大型企業部署**：公司有 100+ 位員工需要使用 MaiAgent，透過 SSO 整合避免逐一建立帳號
2. **統一權限管理**：希望在公司的身分驗證系統中統一管理所有員工的角色和權限
3. **安全性要求**：金融、醫療等高度重視資安的產業，要求員工存取所有系統都必須通過企業認證
4. **多系統整合**：公司已使用多個 SaaS 服務，希望員工能用同一組帳密登入所有系統
5. **離職管理**：當員工離職時，只需在企業端停用帳號，即可同時撤銷 MaiAgent 的存取權限

## 進入第三方登入設定

1. 從左側選單點選 <mark style="color:blue;">組織設定</mark> > <mark style="color:blue;">組織概覽</mark>
2. 點擊 <mark style="color:blue;">第三方登入設定</mark> 按鈕
3. 進入認證來源設定頁面，選擇認證類型

{% hint style="warning" %}
只有組織的 **擁有者（Owner）** 才有權限修改第三方登入設定。若您未看到設定按鈕，請確認您的角色權限。
{% endhint %}

## 支援的認證類型

MaiAgent 提供 4 種認證方式，您可以依據企業需求選擇最適合的方案：

| 認證類型                                                          | 說明                     | 適用場景                                     |
| ------------------------------------------------------------- | ---------------------- | ---------------------------------------- |
| **MaiAgent**（預設）                                              | 使用 MaiAgent 內建帳號密碼     | 小型團隊、無企業 SSO 需求                          |
| [**SAML**](https://docs.maiagent.ai/org/sso/sso-saml)         | 整合 SAML 2.0 身分提供者（IdP） | 已建置 Azure AD、Okta、Google Workspace 等 IdP |
| [**EIP**](https://docs.maiagent.ai/org/sso/sso-eip)           | 企業資訊入口，透過 API 串接企業驗證系統 | 自建身分驗證系統、需要彈性整合                          |
| [**Keycloak**](https://docs.maiagent.ai/org/sso/sso-keycloak) | 整合 Keycloak 開源身分驗證平台   | 使用 Keycloak 做統一身分管理的企業                   |

進入設定頁面後，畫面會顯示 4 種認證類型的卡片式選單。目前使用中的認證類型會標示綠色「使用中」徽章。點選目標認證類型即可展開對應的設定表單。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-dc77ffe4400c3467a56b02cf7b5c8aea4037751b%2Forg-sso-overview.png?alt=media" alt="第三方登入設定"><figcaption><p>第三方登入設定頁面，可選擇不同的認證方式</p></figcaption></figure>

各認證類型的詳細設定步驟，請參閱：

* [SAML 整合](https://docs.maiagent.ai/org/sso/sso-saml)
* [EIP 整合](https://docs.maiagent.ai/org/sso/sso-eip)
* [Keycloak 整合](https://docs.maiagent.ai/org/sso/sso-keycloak)

## 認證來源名稱規則

無論選擇哪一種第三方認證類型，都需要設定一個 **認證來源名稱**。此名稱具有以下規則：

* 只能使用 **小寫英文字母**、**數字**、**連字號（-）** 和 **底線（\_）**
* 最長 **31 個字元**
* 在整個系統中必須 **唯一**（不區分大小寫）
* 不可使用保留名稱 `maiagent`

{% hint style="info" %}
認證來源名稱會作為系統 URL 的一部分（如 SAML 的 Entity ID 和 ACS URL），設定後如需變更，需要同步更新身分提供者端的設定。建議使用貴公司的英文簡稱作為名稱。
{% endhint %}

## 使用者登入流程

### 首次登入

當員工首次透過 SSO 登入 MaiAgent：

1. 點擊 SSO 登入連結（Login URL）
2. 系統導向企業身分驗證頁面（IdP / EIP / Keycloak）
3. 在企業端完成身分驗證
4. 驗證成功後自動導回 MaiAgent
5. 系統自動建立該員工的 MaiAgent 帳號，設定顯示名稱和認證來源
6. 若有角色資訊（EIP），自動套用對應的角色和權限
7. 員工進入 MaiAgent 管理後台

### 後續登入

1. 若企業系統的 Session 仍有效，可能直接進入 MaiAgent（視 IdP 設定）
2. 若 Session 已過期，需重新在企業端驗證
3. 每次登入時自動更新使用者資訊（名稱、認證來源）
4. EIP 登入會同步更新角色分配

### 登出行為

| 認證類型                                                      | MaiAgent 登出時                            | 企業端登出時                   |
| --------------------------------------------------------- | --------------------------------------- | ------------------------ |
| [SAML](https://docs.maiagent.ai/org/sso/sso-saml)         | 結束 MaiAgent Session，同時向 IdP 發送 SLO 請求   | 所有已整合的 SP 都會收到登出通知       |
| [EIP](https://docs.maiagent.ai/org/sso/sso-eip)           | 僅結束 MaiAgent Session                    | 依企業端設定而定                 |
| [Keycloak](https://docs.maiagent.ai/org/sso/sso-keycloak) | 結束 MaiAgent Session + 撤銷 Keycloak Token | Keycloak 端的 Session 同步結束 |

## 權限管理

### 角色同步機制

| 功能      | [SAML](https://docs.maiagent.ai/org/sso/sso-saml) | [EIP](https://docs.maiagent.ai/org/sso/sso-eip) | [Keycloak](https://docs.maiagent.ai/org/sso/sso-keycloak) |
| ------- | ------------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------- |
| 使用者自動建立 | 首次登入時                                             | 首次登入時                                           | 首次登入時                                                     |
| 角色自動同步  | 不支援                                               | 支援（每次登入）                                        | 不支援                                                       |
| 同步策略    | -                                                 | 完整替換                                            | -                                                         |
| 角色來源    | MaiAgent 手動指派                                     | EIP 回傳 groupIds                                 | MaiAgent 手動指派                                             |

### MaiAgent 端的額外設定

無論使用哪種 SSO 認證類型，MaiAgent 管理員都可以：

1. 為同步的角色設定可存取的 AI 助理、知識庫等資源
2. 調整角色的權限範圍
3. 手動為使用者加入額外的 MaiAgent 本地角色

{% hint style="info" %}
使用 EIP 的角色自動同步時，建議事先在 MaiAgent 中建立並設定好角色權限，這樣員工登入時就能直接繼承正確的權限。
{% endhint %}

### 權限更新時機

| 時機        | 說明                       |
| --------- | ------------------------ |
| 每次 SSO 登入 | 更新使用者名稱、認證來源；EIP 同步角色    |
| 手動調整      | 管理員在 MaiAgent 後台手動修改角色分配 |

## 切換認證類型

MaiAgent 支援在不同認證類型之間切換。切換時請注意：

### 從 MaiAgent 切換到第三方認證

* 系統會建立新的認證來源設定
* 現有使用者的認證來源不會立即變更，待下次使用新的 SSO 方式登入時自動更新
* 組織會被標記為該認證來源的預設組織

### 從第三方認證切換回 MaiAgent

* 所有透過 SSO 建立的使用者將被重新指向 MaiAgent 預設認證
* 舊的第三方認證來源設定會被刪除
* 使用者需使用 MaiAgent 帳號密碼登入（可能需要重設密碼）

### 在第三方認證之間切換

* 舊的認證設定會被清空並套用新設定
* 使用者需使用新的 SSO 方式登入

{% hint style="warning" %}
切換認證類型是重大操作，請確保新的認證設定已在企業端完成並測試通過後再執行。儲存時系統會跳出確認視窗，請仔細閱讀提醒事項。
{% endhint %}

## 安全性考量

### 傳輸安全

* 所有認證流程使用 HTTPS 加密傳輸
* SAML 回應支援 XML 簽章驗證
* Keycloak 整合使用 JWT Token 驗證
* MaiAgent 不儲存企業端的密碼資訊

### 存取控制

* 只有通過企業驗證的員工才能透過 SSO 登入
* 員工離職時，企業端停用帳號即可撤銷 MaiAgent 存取權限
* 認證來源設定僅限組織擁有者操作
* 企業版方案才能使用第三方認證功能

## 疑難排解

### 登入失敗

**問題：點擊 SSO 登入後顯示錯誤訊息**

| 可能原因               | 解決方式                             |
| ------------------ | -------------------------------- |
| IdP / EIP 設定錯誤     | 檢查 MaiAgent 後台填寫的 URL 是否正確       |
| SP 資訊未正確設定在 IdP 端  | 確認 Entity ID 和 ACS URL 已正確填入 IdP |
| 使用者未被指派到企業應用程式     | 在 IdP 端將使用者加入應用程式的使用者清單          |
| SAML 回應缺少 Email 屬性 | 確認 IdP 端有設定傳送 Email Claim        |
| 認證來源名稱不匹配          | 確認 MaiAgent 設定的名稱與 URL 中的名稱一致    |
| 非企業版方案             | 確認組織已升級為企業版                      |

### 角色未正確同步（EIP）

**問題：登入後沒有預期的角色權限**

1. 確認 EIP 伺服器回傳的 `groupIds` 內容正確
2. 確認 `groupIds` 中的角色 ID 已在 MaiAgent 中建立
3. 確認未在 `groupIds` 中包含 DEFAULT 類型的角色（系統會自動套用）
4. 嘗試登出後重新登入

### 使用者資訊未更新

**問題：在企業端更改資料後，MaiAgent 仍顯示舊資料**

1. 登出 MaiAgent 後重新登入（SSO 登入時會自動更新）
2. 清除瀏覽器快取
3. 確認 IdP / EIP 端有正確回傳最新的使用者資訊

### 設定頁面顯示「企業版專屬功能」

**問題：無法看到認證類型設定表單**

此功能需要企業版方案。請聯繫 MaiAgent 業務團隊升級方案。

### 無法儲存設定

**問題：點擊儲存後顯示錯誤**

1. 確認所有必填欄位已填寫
2. 確認認證來源名稱符合格式要求（小寫英數 + 連字號）
3. 確認認證來源名稱未與其他組織重複
4. 確認 URL 欄位的格式正確（包含 `https://`）

## 常見問題

**Q：SSO 整合需要多久時間？**\
A：在 MaiAgent 後台的設定可以即時完成。整體時間取決於企業端的設定準備。若企業端資訊都已就緒，通常數小時內即可完成整合與測試。

**Q：啟用 SSO 後，現有的一般帳號還能使用嗎？**\
A：可以。SSO 啟用後不會自動停用一般帳號登入。但基於安全性考量，建議與 MaiAgent 團隊討論是否要停用一般登入方式。

**Q：員工離職後需要在 MaiAgent 手動刪除帳號嗎？**\
A：不需要。只要在企業端停用該員工的帳號，該員工就無法再透過 SSO 登入 MaiAgent。

**Q：可以部分員工使用 SSO，部分使用一般帳密嗎？**\
A：可以。系統支援混合登入模式。例如正職員工使用 SSO，外部顧問使用一般帳號密碼。

**Q：SSO 整合需要額外費用嗎？**\
A：SSO 整合屬於企業版功能。若您的方案已包含企業功能，則不需額外付費。詳細的方案內容請洽業務團隊。

**Q：一個組織可以同時設定多種 SSO 方式嗎？**\
A：目前每個組織只能設定一種認證類型。如需切換，可在後台直接變更。

**Q：EIP 角色同步是如何運作的？**\
A：當使用 EIP 登入時，系統會讀取 EIP 回傳的角色清單（`groupIds`），並自動同步到 MaiAgent。每次登入都會同步，採用完整替換策略（以 EIP 回傳的角色為準），確保權限與企業端保持一致。

**Q：Keycloak 整合中，虛擬 Email 會被用來寄信嗎？**\
A：不會。虛擬 Email（`{username}@{email_domain}`）僅作為 MaiAgent 系統內部的使用者唯一識別用途，不會用於實際的 Email 發送。

**Q：如何確認 SAML 的 SP 資訊是否正確？**\
A：在 MaiAgent 後台填寫認證來源名稱後，SP 資訊（Entity ID、ACS URL）會自動顯示在設定頁面中，您可以直接複製使用。

## 延伸閱讀

* 角色權限的詳細設定，請參閱 [角色權限管理](https://docs.maiagent.ai/org/role-permission)
* 組織管理功能，請參閱 [組織管理](https://docs.maiagent.ai/org/organization)


---

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