> 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/org/sso/sso-eip.md).
# EIP 整合
透過 EIP 整合串接企業既有的身分驗證系統，支援彈性參數傳遞與角色自動同步
EIP（Enterprise Information Portal）提供彈性的企業整合方案，透過 API 串接企業既有的身分驗證系統。
**適用對象**：擁有自建身分驗證系統的企業，或需要客製化整合邏輯的組織
**主要優勢**：
* 整合流程較為簡化
* 支援彈性的參數傳遞，不限於固定參數名稱
* 可依企業需求調整整合方式
* 支援角色資訊自動同步
## 設定步驟
### 1. 在 MaiAgent 後台填寫 EIP 設定
選擇 EIP 認證類型後，需要填寫以下欄位：
| 欄位 | 必填 | 說明 |
| ---------------------------------------- | -- | -------------------------------------------------------- |
| 認證來源名稱 | 是 | 認證來源的英文代號，例如 `company-eip` |
| 伺服器 URL | 是 | EIP 伺服器的驗證 API 端點，例如 `https://eip.internal.com/api/auth` |
填寫完成後，系統會自動產生 **Login URL**，格式為：
```
https://{前端域名}/auth/eip?serverUrl={EIP 伺服器 URL}
```
### 2. 設定 EIP 伺服器
確保您的 EIP 伺服器具備以下能力：
1. 接收 MaiAgent 傳送的 payload 參數（支援 GET 和 POST 方法）
2. 根據 payload 內容驗證使用者身分
3. 回傳使用者資訊，格式如下：
```json
{
"email": "user@company.com",
"name": "王小明",
"groupIds": ["group-a", "group-b"]
}
```
| 回傳欄位 | 必要 | 說明 |
| ---------- | -- | ---------------------------------------------------------------- |
| `email` | 是 | 使用者電子郵件，作為唯一識別 |
| `name` | 是 | 使用者顯示名稱。沒有回傳時登入會失敗；每次登入都會以這個值更新顯示名稱 |
| `groupIds` | 否 | 使用者所屬角色 ID（UUID）清單，用於自動同步 MaiAgent 角色，見[角色自動同步](#role-auto-sync) |
### 3. 測試登入流程
使用 Login URL 加上 EIP 系統產生的參數進行測試：
```
# 範例 1：包含 SessionId（舊版相容）
https://{前端域名}/auth/eip?serverUrl=https://eip.company.com&sessionId=abc123
# 範例 2：不包含 SessionId（新版支援）
https://{前端域名}/auth/eip?serverUrl=https://eip.company.com&userId=12345&token=xyz789
# 範例 3：自訂參數
https://{前端域名}/auth/eip?serverUrl=https://eip.company.com&customParam1=value1&customParam2=value2
```
{% hint style="info" %}
`sessionId` 在最新版本中為選用參數。系統會自動收集 URL 中除 `serverUrl` 以外的所有查詢參數作為 payload，傳送給 EIP 伺服器驗證。
{% endhint %}
### 4. 儲存設定
確認測試通過後，在 MaiAgent 後台點擊 儲存 完成設定。
## EIP 參數處理邏輯
MaiAgent 收到 EIP 登入請求時的處理方式：
1. 分離 `serverUrl` 參數
2. 將其他所有查詢參數收集為 `payload` 物件
3. 將 `payload` 附加固定參數（`op=maiagent`、`type=json`）後傳送給 EIP 伺服器
4. EIP 伺服器支援 GET 和 POST 兩種接收方式，可在 payload 中透過 `method` 欄位指定
## 登入失敗的訊息
使用者從 EIP 導向 MaiAgent 後，畫面會先顯示「EIP 登入中...」；失敗時在下方以紅字顯示原因：
| 畫面訊息 | 常見原因 | 處理方式 |
| ------------------- | ----------------------------------- | ------------------------------------------------------------------------ |
| 缺少必要的參數 (serverUrl) | 導向網址少了 `serverUrl` 參數 | 檢查 EIP 端產生的導向網址，`serverUrl` 必須指向您的 EIP 驗證端點 |
| API 登入失敗 | MaiAgent 向 EIP 伺服器驗證後未取得有效的使用者資料 | 確認 EIP 端依[設定 EIP 伺服器](#step-2-configure-eip-server)回傳 `email`、`name` 等欄位 |
| API 登入過程發生錯誤 | MaiAgent 連不上 `serverUrl`，或 EIP 回傳錯誤 | 確認 MaiAgent 伺服器可連到 EIP 的驗證端點（防火牆、憑證），再查 EIP 端的錯誤記錄 |
## EIP 重新導向路徑
EIP 登入支援兩種路徑，功能完全相同，查詢參數的用法也一樣：
| 路徑 | 說明 |
| -------------------- | -------------------------------------- |
| `/auth/eip` | 標準路徑 |
| `/auth/eip/redirect` | 相容路徑，給 EIP 端必須以 `redirect` 結尾的重新導向需求使用 |
## 角色自動同步
EIP 整合支援角色資訊自動同步，這是 EIP 最強大的功能之一：
1. 企業端在 EIP 回傳的使用者資訊中包含 `groupIds` 角色清單
2. MaiAgent 接收後自動將使用者分配到對應角色
3. 只取代 **由 EIP 指派的角色**：先移除這位使用者先前由 EIP 指派、但這次不在清單中的角色，再加入清單中的角色。管理員在後台手動指派的角色、由 LDAP 或 SCIM 指派的角色都會保留
4. 每次登入都會同步，確保由 EIP 管理的角色與企業端保持一致
| EIP 回傳的 `groupIds` | 結果 |
| ------------------ | ----------------- |
| 角色 ID 清單 | 由 EIP 指派的角色改成這份清單 |
| 空陣列 `[]` | 移除所有由 EIP 指派的角色 |
| 沒有這個欄位或為 `null` | 不變動角色 |
{% hint style="warning" %}
`groupIds` 代表「EIP 要指派的完整角色清單」：清單中沒有的角色，若先前是由 EIP 指派，下次登入就會被移除。請確保 EIP 端回傳的角色清單是完整的。
{% endhint %}
{% hint style="info" %}
如果 `groupIds` 中包含 MaiAgent 中尚未建立的角色 ID，系統會回傳驗證錯誤。建議事先在 MaiAgent 中建立好對應的角色。
{% endhint %}
## EIP 安全注意事項
* 務必在 EIP 伺服器端驗證所有參數，不僅依賴客戶端驗證
* 確保驗證 Token 有時效性限制，避免重放攻擊
* 務必使用 HTTPS 連線，保護傳輸過程中的敏感資訊
* EIP 伺服器應驗證所有接收到的參數，防止注入攻擊
## 設定欄位速查表
| 欄位 | 必填 | 格式 | 範例 |
| ------- | -- | -------------------- | ---------------------------------- |
| 認證來源名稱 | 是 | 小寫英數 + 連字號，max 31 字元 | `company-eip` |
| 伺服器 URL | 是 | HTTPS URL | `https://eip.company.com/api/auth` |
---
# 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/org/sso/sso-eip.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.