# 第三方登入（SSO）
企業單一登入（Single Sign-On, SSO）功能讓您的員工能夠使用公司既有的帳號系統登入 MaiAgent 平台，無需額外記憶新的帳號密碼。透過與企業身分驗證系統整合，員工只要登入一次公司系統，就能無縫存取 MaiAgent 的所有功能，大幅簡化登入流程並提升安全性。
{% hint style="info" %}
第三方登入（SSO）為 **企業版** 專屬功能。如需啟用，請聯繫 MaiAgent 業務團隊升級至企業方案。
{% endhint %}
## 使用場景
1. **大型企業部署**：公司有 100+ 位員工需要使用 MaiAgent，透過 SSO 整合避免逐一建立帳號
2. **統一權限管理**：希望在公司的身分驗證系統中統一管理所有員工的角色和權限
3. **安全性要求**：金融、醫療等高度重視資安的產業，要求員工存取所有系統都必須通過企業認證
4. **多系統整合**：公司已使用多個 SaaS 服務，希望員工能用同一組帳密登入所有系統
5. **離職管理**：當員工離職時，只需在企業端停用帳號，即可同時撤銷 MaiAgent 的存取權限
## 進入第三方登入設定
1. 從左側選單點選 組織設定 > 組織概覽
2. 點擊 第三方登入設定 按鈕
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 種認證類型的卡片式選單。目前使用中的認證類型會標示綠色「使用中」徽章。點選目標認證類型即可展開對應的設定表單。
第三方登入設定頁面，可選擇不同的認證方式
各認證類型的詳細設定步驟，請參閱：
* [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)