SSO 與身分整合總覽

MaiAgent 支援的登入與身分整合方式總覽：內建帳號、SAML、EIP、Keycloak、Cloudflare Access、LDAP 帳密登入與 Google 帳號登入，各自的適用情境、設定入口，以及和成員開通的搭配

這頁幫客戶 IT 與 SI 夥伴先選對身分整合方式：MaiAgent 支援哪些登入方式、各自適合什麼環境、要準備哪些資訊，以及登入（SSO）和成員開通（SCIM、LDAP 同步）怎麼搭配。選定後，再到對應頁面看設定細節。

和使用者手冊的分工：後台設定步驟見使用者手冊第三方登入（SSO）與其子頁；本頁只寫各方式的技術規格、選型與搭配。

登入與開通是兩件事

問題	由誰處理	相關頁面
人員怎麼證明身分、登入 MaiAgent 網頁、MaiGPT 或 App	登入方式（本頁）	本頁、SAML SSO 單一登入整合
人員什麼時候成為組織成員、離職時誰來停用、角色怎麼同步	成員開通	成員開通：SCIM／邀請／SSO

SSO 只在登入當下建立帳號或檢查身分。員工在 IdP 被停用後，MaiAgent 不會自動停用他的成員資格；離職停用請靠 SCIM、身分同步或後台停用。

啟用 SSO 也不會停用既有帳號的密碼登入：帳號原本有 MaiAgent 密碼時，仍可用 Email＋密碼登入，平台沒有「只允許 SSO 登入」的設定。後台的停用方式見使用者手冊離職與停用成員。

組織可設定的登入方式

設定入口：組織設定 → 組織概覽 → 第三方登入設定。這是企業版功能，只有組織擁有者能修改。

方式	機制	要在 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 使用者名稱>@<虛擬信箱網域>	不同步	已用 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 整合（含 ADFS 整合）、EIP 整合、Keycloak 整合、Cloudflare Access 整合。SAML 的 SP 規格、屬性與帳號比對規則，見技術手冊SAML SSO 單一登入整合；Cloudflare Access 的 JWT 驗證方式見下方。

電子郵件網域在各方式的意義

同一個欄位在不同方式下用途不同。一個網域在整個平台只能被一個認證來源使用，重複時儲存會失敗（This email domain is already in use.）。

方式	是否必填	用途
SAML	選填	成員在登入頁輸入這個網域的信箱時，自動導向這個 SAML 登入（SaaS 登入頁已啟用；地端依部署設定）。網域須完全相同，[e-mail] 不會對應到 acme.com
Keycloak	必填	組成成員帳號的 Email（虛擬信箱）
Cloudflare Access	選填	只允許這個網域的信箱透過 Cloudflare Access 登入

Cloudflare Access

適合已經用 Cloudflare Zero Trust 管理員工存取的組織：員工先通過 Cloudflare Access 驗證，MaiAgent 再信任 Cloudflare 簽發的身分。要填的欄位（伺服器 URL、Team Name、AUD Tag、電子郵件網域、自動建立成員）與帳號對應規則，見使用者手冊Cloudflare Access 整合。

登入時，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）
Google 帳號登入	SaaS 登入頁的 使用 Google 登入。以 Google 驗證過的 Email 對應既有帳號，沒有就建立新帳號	由平台提供，組織無法設定；成員資格仍依邀請、SCIM 或組織的 SSO 決定

和成員開通怎麼搭配

您的環境	建議組合
IdP 支援 SCIM（Entra ID、Okta、JumpCloud）	SCIM 管名單、角色與離職停用，SAML 管登入。見成員開通：SCIM
AD 或其他 LDAP 目錄	LDAP 身分同步管名單與角色，再選 LDAP 帳密登入，或用 ADFS 走 SAML
自建入口網站	EIP 管登入，登入時同步角色；名單與停用另用名單同步工具或後台處理
員工只在自家系統裡用 MaiGPT	不需要 SSO：用 SCIM 或即時同步開通，再以成員身分嵌入

OAuth 授權頁只接受 Email 與密碼登入。只用 SSO、沒有 MaiAgent 密碼的成員，要讓 Claude 等 MCP 客戶端連線時，請改用 API Key。詳見MaiAgent 作為 OAuth 2.1 授權伺服器。

常見問題

可以同時啟用 SAML 和 Keycloak 嗎？

不行。一個組織同一時間只有一種登入方式，改選另一種會覆蓋原設定。不同部門要用不同 IdP 時，請在 IdP 端整合成同一個入口。

為什麼在第三方登入設定裡看不到 LDAP？

LDAP 的帳密登入綁在身分同步上：必須先完成 LDAP 同步，才能在 身分同步 裡開啟。第三方登入設定只管 SAML、EIP、Keycloak 與 Cloudflare Access。

看不到第三方登入設定或無法儲存？

第三方登入是企業版功能，而且只有組織擁有者能修改。非企業版組織儲存時會收到 Only enterprise plan can modify third-party authentication.。