第三方登入（SSO）

登入方式總覽

MaiAgent 平台提供多種登入方式，滿足不同企業的身份驗證需求：

登入方式	適用情境	特點	角色自動同步
標準登入	一般用戶	Email + 密碼，支援註冊新帳號	-
Keycloak SSO	企業單一登入	整合企業身份管理系統	-
Azure AD / SAML	Microsoft 企業環境	使用公司 Microsoft 帳號登入	-
EIP 登入	企業入口平台	整合企業內部系統 Session	✅ 支援

關於第三方登入入口

標準登入頁面僅提供 Email + 密碼登入。第三方登入（Keycloak、Azure AD、EIP）需透過指定網址存取，請向貴公司 IT 管理員取得正確的登入網址。

---

什麼是第三方登入？

第三方登入（SSO，Single Sign-On）讓使用者可以透過企業既有的身份驗證系統登入 MaiAgent，無需另外記憶新的帳號密碼。常見的企業身份驗證系統包括：

• Keycloak：開源的身份與存取管理解決方案

• Azure AD：Microsoft 的雲端身份服務

• EIP：企業入口平台（Enterprise Information Portal）

---

Keycloak SSO 登入流程

Keycloak 是一種常見的企業級身份驗證解決方案，支援 OpenID Connect、OAuth 2.0 等協定。

sequenceDiagram
    participant User as 使用者
    participant MaiAgent as MaiAgent 平台
    participant Keycloak as Keycloak 伺服器
    
    User->>MaiAgent: 1. 點擊 Keycloak 登入
    MaiAgent->>Keycloak: 2. 重新導向至 Keycloak 登入頁
    User->>Keycloak: 3. 輸入企業帳號密碼
    Keycloak->>Keycloak: 4. 驗證身份
    Keycloak->>MaiAgent: 5. 回傳 Access Token
    MaiAgent->>MaiAgent: 6. 驗證 Token 並建立 Session
    MaiAgent->>User: 7. 登入成功，進入平台

流程說明：

1. 使用者在 MaiAgent 選擇 Keycloak 登入方式

2. 系統將使用者導向企業的 Keycloak 登入頁面

3. 使用者輸入企業內部的帳號密碼

4. Keycloak 驗證使用者身份

5. 驗證成功後，Keycloak 將認證資訊回傳給 MaiAgent

6. MaiAgent 建立使用者 Session

7. 使用者成功登入並可開始使用平台

---

Azure AD (SAML) 登入流程

Azure AD 使用 SAML 協定進行身份驗證，適合使用 Microsoft 365 或 Azure 服務的企業。

sequenceDiagram
    participant User as 使用者
    participant MaiAgent as MaiAgent 平台
    participant AzureAD as Azure AD
    
    User->>MaiAgent: 1. 點擊 Azure AD 登入
    MaiAgent->>AzureAD: 2. 發送 SAML 驗證請求
    User->>AzureAD: 3. 使用 Microsoft 帳號登入
    AzureAD->>AzureAD: 4. 驗證身份
    AzureAD->>MaiAgent: 5. 回傳 SAML 斷言（含認證碼）
    MaiAgent->>MaiAgent: 6. 交換 Token 並建立 Session
    MaiAgent->>User: 7. 登入成功，進入平台

流程說明：

1. 使用者在 MaiAgent 選擇 Azure AD 登入

2. 系統發送 SAML 驗證請求至 Azure AD

3. 使用者使用公司的 Microsoft 帳號登入

4. Azure AD 驗證使用者身份

5. 驗證成功後，Azure AD 回傳 SAML 斷言與認證碼

6. MaiAgent 使用認證碼交換存取權杖

7. 使用者成功登入平台

---

EIP 登入流程

EIP（企業入口平台）登入適用於已有企業內部系統的組織，透過 Session ID 進行身份傳遞。

sequenceDiagram
    participant User as 使用者
    participant EIP as 企業入口平台
    participant MaiAgent as MaiAgent 平台
    
    User->>EIP: 1. 登入企業入口平台
    EIP->>EIP: 2. 建立 Session
    User->>EIP: 3. 點擊 MaiAgent 連結
    EIP->>MaiAgent: 4. 傳遞 Session ID
    MaiAgent->>EIP: 5. 驗證 Session 有效性
    EIP->>MaiAgent: 6. 回傳使用者資訊
    MaiAgent->>MaiAgent: 7. 建立 MaiAgent Session
    MaiAgent->>User: 8. 登入成功，進入平台

流程說明：

1. 使用者先登入企業內部的入口平台

2. EIP 系統建立使用者 Session

3. 使用者從 EIP 點擊進入 MaiAgent

4. EIP 將 Session ID 傳遞給 MaiAgent

5. MaiAgent 向 EIP 驗證 Session 是否有效

6. EIP 回傳該使用者的基本資訊（包含角色資訊）

7. MaiAgent 建立對應的平台 Session，並自動同步角色

8. 使用者成功登入並可使用平台

---

EIP 角色自動同步機制

EIP 登入支援角色自動同步功能，讓企業能夠在 EIP 端統一管理使用者角色，MaiAgent 會自動同步對應的權限。

sequenceDiagram
    participant User as 使用者
    participant EIP as 企業入口平台
    participant MaiAgent as MaiAgent 平台
    
    User->>EIP: 1. 登入 EIP
    EIP->>MaiAgent: 2. 傳遞 Session ID
    MaiAgent->>EIP: 3. 請求使用者資訊
    EIP->>MaiAgent: 4. 回傳使用者資訊 + 角色清單（groupIds）
    MaiAgent->>MaiAgent: 5. 比對並同步角色
    Note over MaiAgent: 移除舊角色，套用新角色
    MaiAgent->>User: 6. 登入完成，權限已更新

同步機制特點：

• 即時同步：每次登入都會重新同步角色，確保權限與 EIP 端一致

• 完整替換：系統會以 EIP 回傳的角色清單為準，完整替換現有角色

• 自動生效：同步完成後，使用者立即獲得新權限，無需額外操作

適用情境

• 員工調動時，IT 只需在 EIP 端更新角色，使用者下次登入 MaiAgent 就會自動獲得新權限

• 新進員工在 EIP 設定好角色後，首次登入即擁有對應權限

• 離職員工在 EIP 停用後，無法再登入 MaiAgent

• 若需手動管理權限，請參閱 批次成員與權限管理

注意事項

• EIP 需回傳 groupIds 參數，包含使用者應有的角色 ID 清單

• 角色 ID 需與 MaiAgent 組織中的角色 ID 對應

• 若 EIP 未回傳 groupIds，系統將保留使用者現有角色

---

登入網址說明

不同的第三方登入方式有不同的網址格式，以下為各登入方式的網址說明：

登入方式	網址格式	範例
標準登入	https://{domain}/login	https://admin.maiagent.ai/login
Azure AD / SAML	https://{domain}/auth/saml/{authSource}	https://admin.maiagent.ai/auth/saml/company-name
Keycloak	前端整合，由登入頁按鈕觸發	-
EIP	從企業入口平台跳轉，帶參數	https://{domain}/auth/eip?sessionId=xxx

authSource 參數說明

authSource 是企業在 MaiAgent 設定的認證來源名稱，由系統管理員在後台設定。企業使用者應向 IT 管理員取得正確的登入網址。

---

常見問題

Q：透過第三方登入的新成員會有什麼權限？

新成員加入組織後，會自動獲得「預設角色」的權限，這適用於所有登入方式（包含第三方登入）。管理員可以在 角色權限管理 中調整預設角色的權限範圍。

Q：第三方登入失敗時該怎麼辦？

1. 確認企業的身份驗證服務（Keycloak/Azure AD/EIP）是否正常運作

2. 檢查登入網址是否正確：

   • Azure AD/SAML：https://{domain}/auth/saml/{authSource}

   • EIP：確認 Session ID 是否有效

3. 確認使用者在企業身份系統中的帳號狀態是否正常

4. 如問題持續，請聯繫系統管理員或 MaiAgent 技術支援

Q：可以同時使用多種登入方式嗎？

是的，MaiAgent 支援同時啟用多種登入方式。同一位使用者可以透過不同方式登入，只要 Email 相同，系統會自動識別為同一帳號並關聯。

範例：

• 使用者先用 Email + 密碼註冊帳號

• 之後公司啟用 Azure AD 登入

• 使用者透過 Azure AD 登入時，系統會自動將 Azure AD 帳號與原有帳號關聯

• 之後兩種方式都可以登入同一帳號

Q：EIP 角色同步是如何運作的？

當使用 EIP 登入時，系統會讀取 EIP 回傳的角色清單（groupIds），並自動同步到 MaiAgent：

• 每次登入都會同步：確保權限與 EIP 端保持一致

• 完整替換策略：以 EIP 回傳的角色為準，移除不在清單中的舊角色

• 即時生效：同步完成後立即擁有新權限

這讓 IT 管理員只需在 EIP 端管理角色，員工調動或權限變更時無需額外在 MaiAgent 操作。

Q：Azure AD 登入支援角色自動同步嗎？

目前 Azure AD（SAML）登入尚未支援角色自動同步功能。若您需要此功能，請聯繫 MaiAgent 技術團隊討論客製化方案。

現階段 Azure AD 使用者的角色管理方式：

• 新成員登入後自動獲得預設角色

• 管理員可透過 批次成員與權限管理 功能分配額外角色

---

延伸閱讀

• 角色權限的詳細設定，請參閱[[LINK→角色權限管理]]

• 手動批次管理成員權限，請參閱[[LINK→批次成員與權限管理]]