第三方登入（SSO）
設定企業 SSO 整合（SAML / EIP / Keycloak），讓員工使用公司帳號登入 MaiAgent
企業單一登入（Single Sign-On, SSO）功能讓您的員工能夠使用公司既有的帳號系統登入 MaiAgent 平台，無需額外記憶新的帳號密碼。透過與企業身分驗證系統整合，員工只要登入一次公司系統，就能無縫存取 MaiAgent 的所有功能，大幅簡化登入流程並提升安全性。
第三方登入（SSO）為 企業版 專屬功能。如需啟用，請聯繫 MaiAgent 業務團隊升級至企業方案。
使用場景
大型企業部署：公司有 100+ 位員工需要使用 MaiAgent，透過 SSO 整合避免逐一建立帳號
統一權限管理：希望在公司的身分驗證系統中統一管理所有員工的角色和權限
安全性要求：金融、醫療等高度重視資安的產業，要求員工存取所有系統都必須通過企業認證
多系統整合：公司已使用多個 SaaS 服務，希望員工能用同一組帳密登入所有系統
離職管理：當員工離職時，只需在企業端停用帳號，即可同時撤銷 MaiAgent 的存取權限
進入第三方登入設定
從左側選單點選 組織設定 > 組織概覽
點擊 第三方登入設定 按鈕
進入認證來源設定頁面，選擇認證類型
只有組織的 擁有者（Owner） 才有權限修改第三方登入設定。若您未看到設定按鈕，請確認您的角色權限。
支援的認證類型
MaiAgent 提供 4 種認證方式，您可以依據企業需求選擇最適合的方案：
進入設定頁面後，畫面會顯示 4 種認證類型的卡片式選單。目前使用中的認證類型會標示綠色「使用中」徽章。點選目標認證類型即可展開對應的設定表單。
各認證類型的詳細設定步驟，請參閱：
認證來源名稱規則
無論選擇哪一種第三方認證類型，都需要設定一個 認證來源名稱。此名稱具有以下規則：
只能使用 小寫英文字母、數字、連字號（-） 和 底線（_）
最長 31 個字元
在整個系統中必須 唯一（不區分大小寫）
不可使用保留名稱
maiagent
認證來源名稱會作為系統 URL 的一部分（如 SAML 的 Entity ID 和 ACS URL），設定後如需變更，需要同步更新身分提供者端的設定。建議使用貴公司的英文簡稱作為名稱。
使用者登入流程
首次登入
當員工首次透過 SSO 登入 MaiAgent：
點擊 SSO 登入連結（Login URL）
系統導向企業身分驗證頁面（IdP / EIP / Keycloak）
在企業端完成身分驗證
驗證成功後自動導回 MaiAgent
系統自動建立該員工的 MaiAgent 帳號，設定顯示名稱和認證來源
若有角色資訊（EIP），自動套用對應的角色和權限
員工進入 MaiAgent 管理後台
後續登入
若企業系統的 Session 仍有效，可能直接進入 MaiAgent（視 IdP 設定）
若 Session 已過期，需重新在企業端驗證
每次登入時自動更新使用者資訊（名稱、認證來源）
EIP 登入會同步更新角色分配
登出行為
權限管理
角色同步機制
MaiAgent 端的額外設定
無論使用哪種 SSO 認證類型，MaiAgent 管理員都可以：
為同步的角色設定可存取的 AI 助理、知識庫等資源
調整角色的權限範圍
手動為使用者加入額外的 MaiAgent 本地角色
使用 EIP 的角色自動同步時，建議事先在 MaiAgent 中建立並設定好角色權限，這樣員工登入時就能直接繼承正確的權限。
權限更新時機
每次 SSO 登入
更新使用者名稱、認證來源；EIP 同步角色
手動調整
管理員在 MaiAgent 後台手動修改角色分配
切換認證類型
MaiAgent 支援在不同認證類型之間切換。切換時請注意：
從 MaiAgent 切換到第三方認證
系統會建立新的認證來源設定
現有使用者的認證來源不會立即變更，待下次使用新的 SSO 方式登入時自動更新
組織會被標記為該認證來源的預設組織
從第三方認證切換回 MaiAgent
所有透過 SSO 建立的使用者將被重新指向 MaiAgent 預設認證
舊的第三方認證來源設定會被刪除
使用者需使用 MaiAgent 帳號密碼登入（可能需要重設密碼）
在第三方認證之間切換
舊的認證設定會被清空並套用新設定
使用者需使用新的 SSO 方式登入
切換認證類型是重大操作，請確保新的認證設定已在企業端完成並測試通過後再執行。儲存時系統會跳出確認視窗，請仔細閱讀提醒事項。
安全性考量
傳輸安全
所有認證流程使用 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）
問題：登入後沒有預期的角色權限
確認 EIP 伺服器回傳的
groupIds內容正確確認
groupIds中的角色 ID 已在 MaiAgent 中建立確認未在
groupIds中包含 DEFAULT 類型的角色（系統會自動套用）嘗試登出後重新登入
使用者資訊未更新
問題：在企業端更改資料後，MaiAgent 仍顯示舊資料
登出 MaiAgent 後重新登入（SSO 登入時會自動更新）
清除瀏覽器快取
確認 IdP / EIP 端有正確回傳最新的使用者資訊
設定頁面顯示「企業版專屬功能」
問題：無法看到認證類型設定表單
此功能需要企業版方案。請聯繫 MaiAgent 業務團隊升級方案。
無法儲存設定
問題：點擊儲存後顯示錯誤
確認所有必填欄位已填寫
確認認證來源名稱符合格式要求（小寫英數 + 連字號）
確認認證來源名稱未與其他組織重複
確認 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）會自動顯示在設定頁面中，您可以直接複製使用。
延伸閱讀
最後更新於
這有幫助嗎？