> 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/tech/identity-and-access/sso-overview.md).
# SSO 與身分整合總覽
MaiAgent 支援的登入與身分整合方式總覽：內建帳號、SAML、EIP、Keycloak、Cloudflare Access、LDAP 帳密登入與 Google 帳號登入，各自的適用情境、設定入口，以及和成員開通的搭配
這頁幫客戶 IT 與 SI 夥伴先選對身分整合方式：MaiAgent 支援哪些登入方式、各自適合什麼環境、要準備哪些資訊，以及登入（SSO）和成員開通（SCIM、LDAP 同步）怎麼搭配。選定後，再到對應頁面看設定細節。
{% hint style="info" %}
**和使用者手冊的分工**：後台設定步驟見使用者手冊[第三方登入（SSO）](https://docs.maiagent.ai/org/sso)與其子頁；本頁只寫各方式的技術規格、選型與搭配。
{% endhint %}
## 登入與開通是兩件事
| 問題 | 由誰處理 | 相關頁面 |
| ------------------------------------ | -------- | ------------------------------------------------------------------------ |
| 人員怎麼證明身分、登入 MaiAgent 網頁、MaiGPT 或 App | 登入方式（本頁） | 本頁、[SAML SSO 單一登入整合](/tech/identity-and-access/sso-overview/saml-sso.md) |
| 人員什麼時候成為組織成員、離職時誰來停用、角色怎麼同步 | 成員開通 | [成員開通：SCIM／邀請／SSO](/tech/identity-and-access/member-provisioning.md) |
SSO 只在**登入當下**建立帳號或檢查身分。員工在 IdP 被停用後，MaiAgent 不會自動停用他的成員資格；離職停用請靠 SCIM、身分同步或後台停用。
啟用 SSO 也不會停用既有帳號的密碼登入：帳號原本有 MaiAgent 密碼時，仍可用 Email＋密碼登入，平台沒有「只允許 SSO 登入」的設定。後台的停用方式見使用者手冊[離職與停用成員](https://docs.maiagent.ai/org/sso#offboarding)。
## 組織可設定的登入方式
設定入口：組織設定 → 組織概覽 → 第三方登入設定。這是企業版功能，只有組織擁有者能修改。
| 方式 | 機制 | 要在 MaiAgent 填的資訊 | 第一次登入 | 角色同步 | 適合 |
| ----------------- | -------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------- | ----------------------------------------- |
| MaiAgent（預設） | Email＋密碼 | 不需設定 | 經邀請或自行註冊 | — | 小型團隊、沒有 IdP |
| SAML | SAML 2.0，MaiAgent 為 SP | IdP Metadata URL，或 IdP Entity ID＋IdP SSO URL＋X.509 憑證（二選一）；電子郵件網域（選填） | 自動建立帳號並加入組織 | 不同步，只讀取 Email 與顯示名稱 | Entra ID、Okta、Google Workspace、ADFS 等 IdP |
| EIP | MaiAgent 呼叫貴公司 EIP 的 API 取得使用者資料 | 伺服器 URL | 自動建立帳號並加入組織 | EIP 回傳 `groupIds` 時，取代先前由 EIP 指派的角色 | 自建入口網站、沒有標準 IdP |
| Keycloak | Keycloak（OIDC）專用流程 | 伺服器 URL、Realm 名稱、Client ID、虛擬信箱網域 | 自動建立帳號並加入組織，帳號 Email 為 `@<虛擬信箱網域>` | 不同步 | 已用 Keycloak 管理身分 |
| Cloudflare Access | 驗證 Cloudflare Zero Trust 簽發的 JWT | 伺服器 URL、Team Name、AUD Tag；電子郵件網域（選填）；自動建立成員 | 依 自動建立成員：開啟時自動建立並加入；關閉時只放行既有成員 | 不同步 | 已用 Cloudflare Zero Trust 保護內部服務 |
各方式共通的規則：
* 每個組織同一時間只能使用**一種**登入方式。改選其他方式會覆蓋原設定，且無法復原。
* 第三方方式都要填一個 認證來源名稱，全平台唯一，會成為登入連結與 SAML 端點網址的一部分。
* 儲存後，登入連結 卡片會顯示可以發給成員的 登入 URL；EIP 顯示的則是要設定在 EIP 後台的回呼網址。
* 切回 MaiAgent 內建帳號後，成員下次要用 MaiAgent 密碼登入；由 SSO 建立、從未設定密碼的帳號，需要先設定密碼。
* 目前沒有通用的 OIDC 設定。Keycloak 以外的 OIDC 型 IdP，請改用該 IdP 的 SAML 介接。
各方式的設定步驟：[SAML 整合](https://docs.maiagent.ai/org/sso/sso-saml)（含 [ADFS 整合](https://docs.maiagent.ai/org/sso/sso-saml/sso-saml-adfs)）、[EIP 整合](https://docs.maiagent.ai/org/sso/sso-eip)、[Keycloak 整合](https://docs.maiagent.ai/org/sso/sso-keycloak)、[Cloudflare Access 整合](https://docs.maiagent.ai/org/sso/sso-cloudflare-access)。SAML 的 SP 規格、屬性與帳號比對規則，見技術手冊[SAML SSO 單一登入整合](/tech/identity-and-access/sso-overview/saml-sso.md)；Cloudflare Access 的 JWT 驗證方式見[下方](#cloudflare-access)。
## 電子郵件網域在各方式的意義
同一個欄位在不同方式下用途不同。一個網域在整個平台只能被一個認證來源使用，重複時儲存會失敗（`This email domain is already in use.`）。
| 方式 | 是否必填 | 用途 |
| ----------------- | ---- | -------------------------------------------------------------------------------------------------- |
| SAML | 選填 | 成員在登入頁輸入這個網域的信箱時，自動導向這個 SAML 登入（SaaS 登入頁已啟用；地端依部署設定）。網域須完全相同，`user@mail.acme.com` 不會對應到 `acme.com` |
| Keycloak | 必填 | 組成成員帳號的 Email（虛擬信箱） |
| Cloudflare Access | 選填 | 只允許這個網域的信箱透過 Cloudflare Access 登入 |
## Cloudflare Access
適合已經用 Cloudflare Zero Trust 管理員工存取的組織：員工先通過 Cloudflare Access 驗證，MaiAgent 再信任 Cloudflare 簽發的身分。要填的欄位（伺服器 URL、Team Name、AUD Tag、電子郵件網域、自動建立成員）與帳號對應規則，見使用者手冊[Cloudflare Access 整合](https://docs.maiagent.ai/org/sso/sso-cloudflare-access#configure-in-maiagent)。
登入時，MaiAgent 把成員導到 `<伺服器 URL>/api/auth/cloudflare/<認證來源名稱>/callback/`。這個路徑必須經過 Cloudflare Access 並轉送到 MaiAgent，讓 Cloudflare 在請求加上 `Cf-Access-Jwt-Assertion` 標頭。MaiAgent 用該 team 的公開金鑰驗證 JWT 簽章（RS256），比對 AUD 與簽發者，再以 JWT 裡的 Email 對應帳號。驗證失敗或不允許登入時，成員會被導回 MaiAgent 並看到錯誤訊息。
## 不在「第三方登入設定」的登入方式
| 方式 | 說明 | 設定入口 |
| ----------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| LDAP 帳密登入 | 先用身分同步把 LDAP 目錄的人員匯入，再開啟 LDAP 帳密登入：成員在 MaiAgent 登入頁輸入 Email 與企業密碼，由 MaiAgent 向 LDAP 驗證。開啟後，已同步成員原本的 MaiAgent 密碼不再有效 | 組織設定 → 組織概覽 → 身分同步（企業版；開啟或變更只限組織擁有者，具「身分同步權限」的成員可檢視），見使用者手冊[身分同步（LDAP）](https://docs.maiagent.ai/org/sso/identity-sync#ldap-login) |
| Google 帳號登入 | SaaS 登入頁的 使用 Google 登入。以 Google 驗證過的 Email 對應既有帳號，沒有就建立新帳號 | 由平台提供，組織無法設定；成員資格仍依邀請、SCIM 或組織的 SSO 決定 |
## 和成員開通怎麼搭配
| 您的環境 | 建議組合 |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| IdP 支援 SCIM（Entra ID、Okta、JumpCloud） | SCIM 管名單、角色與離職停用，SAML 管登入。見[成員開通：SCIM](/tech/identity-and-access/member-provisioning.md#scim) |
| AD 或其他 LDAP 目錄 | LDAP 身分同步管名單與角色，再選 LDAP 帳密登入，或用 ADFS 走 SAML |
| 自建入口網站 | EIP 管登入，登入時同步角色；名單與停用另用[名單同步工具](/tech/identity-and-access/member-provisioning/member-roster-sync.md)或後台處理 |
| 員工只在自家系統裡用 MaiGPT | 不需要 SSO：用 SCIM 或[即時同步](/tech/identity-and-access/member-provisioning/member-event-sync.md)開通，再以成員身分嵌入 |
{% hint style="warning" %}
只用 SSO、沒有 MaiAgent 密碼的成員，也能從 OAuth 授權頁的組織帳號登入入口，完成後台登入後返回授權頁，讓 Claude 等 MCP 客戶端以成員本人身分連線。詳見[MaiAgent 作為 OAuth 2.1 授權伺服器](/tech/identity-and-access/maiagent-oauth-server.md#login-and-consent)。
{% endhint %}
## 常見問題
可以同時啟用 SAML 和 Keycloak 嗎？
不行。一個組織同一時間只有一種登入方式，改選另一種會覆蓋原設定。不同部門要用不同 IdP 時，請在 IdP 端整合成同一個入口。
為什麼在第三方登入設定裡看不到 LDAP？
LDAP 的帳密登入綁在身分同步上：必須先完成 LDAP 同步，才能在 身分同步 裡開啟。第三方登入設定只管 SAML、EIP、Keycloak 與 Cloudflare Access。
看不到第三方登入設定或無法儲存？
第三方登入是企業版功能，而且只有組織擁有者能修改。非企業版組織儲存時會收到 `Only enterprise plan can modify third-party authentication.`。
---
# 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/tech/identity-and-access/sso-overview.md?ask=&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.