# EIP 整合

EIP（Enterprise Information Portal）提供彈性的企業整合方案，透過 API 串接企業既有的身分驗證系統。

**適用對象**：擁有自建身分驗證系統的企業，或需要客製化整合邏輯的組織

**主要優勢**：

* 整合流程較為簡化
* 支援彈性的參數傳遞，不限於固定參數名稱
* 可依企業需求調整整合方式
* 支援角色資訊自動同步

## 設定步驟 <a href="#setup-steps" id="setup-steps"></a>

### 1. 在 MaiAgent 後台填寫 EIP 設定 <a href="#step-1-fill-eip-settings" id="step-1-fill-eip-settings"></a>

<figure><img src="/files/ajCwaG2YuboUsCOyFeif" alt="EIP 設定"><figcaption><p>EIP 認證設定：填寫認證來源名稱與伺服器 URL</p></figcaption></figure>

選擇 <mark style="color:blue;">EIP</mark> 認證類型後，需要填寫以下欄位：

| 欄位         | 必填 | 說明                         |
| ---------- | -- | -------------------------- |
| 認證來源名稱     | 是  | 認證來源的英文代號，例如 `company-eip` |
| Server URL | 是  | EIP 伺服器的驗證 API 端點          |

填寫完成後，系統會自動產生 **Login URL**，格式為：

```
https://{前端域名}/auth/eip?serverUrl={EIP 伺服器 URL}
```

### 2. 設定 EIP 伺服器 <a href="#step-2-configure-eip-server" id="step-2-configure-eip-server"></a>

確保您的 EIP 伺服器具備以下能力：

1. 接收 MaiAgent 傳送的 payload 參數（支援 GET 和 POST 方法）
2. 根據 payload 內容驗證使用者身分
3. 回傳使用者資訊，格式如下：

```json
{
  "email": "user@company.com",
  "name": "王小明",
  "groupIds": ["group-a", "group-b"]
}
```

| 回傳欄位       | 必要 | 說明                               |
| ---------- | -- | -------------------------------- |
| `email`    | 是  | 使用者電子郵件，作為唯一識別                   |
| `name`     | 否  | 使用者顯示名稱                          |
| `groupIds` | 否  | 使用者所屬角色 ID 清單，用於自動同步 MaiAgent 角色 |

### 3. 測試登入流程 <a href="#step-3-test-login-flow" id="step-3-test-login-flow"></a>

使用 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. 儲存設定 <a href="#step-4-save-settings" id="step-4-save-settings"></a>

確認測試通過後，在 MaiAgent 後台點擊 <mark style="color:blue;">儲存</mark> 完成設定。

## EIP 參數處理邏輯 <a href="#eip-parameter-handling" id="eip-parameter-handling"></a>

MaiAgent 收到 EIP 登入請求時的處理方式：

1. 分離 `serverUrl` 參數
2. 將其他所有查詢參數收集為 `payload` 物件
3. 將 `payload` 附加固定參數（`op=maiagent`、`type=json`）後傳送給 EIP 伺服器
4. EIP 伺服器支援 GET 和 POST 兩種接收方式，可在 payload 中透過 `method` 欄位指定

## EIP 重新導向路徑 <a href="#eip-redirect-path" id="eip-redirect-path"></a>

EIP 登入支援兩種路徑，功能完全相同：

| 路徑                    | 說明               |
| --------------------- | ---------------- |
| `/auth/eip`           | 標準路徑             |
| `/redirect/eip-login` | 相容路徑，適用於特殊重新導向需求 |

## 角色自動同步 <a href="#role-auto-sync" id="role-auto-sync"></a>

EIP 整合支援角色資訊自動同步，這是 EIP 最強大的功能之一：

1. 企業端在 EIP 回傳的使用者資訊中包含 `groupIds` 角色清單
2. MaiAgent 接收後自動將使用者分配到對應角色
3. 採用 **完整替換策略**：以 EIP 回傳的角色為準，移除不在清單中的舊角色
4. 每次登入都會同步，確保權限與企業端保持一致

{% hint style="warning" %}
角色同步採用完整替換策略，意味著 EIP 回傳的角色清單會完全覆蓋使用者在 MaiAgent 中的角色分配。請確保 EIP 端回傳的角色清單是完整的。
{% endhint %}

{% hint style="info" %}
如果 `groupIds` 中包含 MaiAgent 中尚未建立的角色 ID，系統會回傳驗證錯誤。建議事先在 MaiAgent 中建立好對應的角色。
{% endhint %}

## EIP 安全注意事項 <a href="#eip-security-notes" id="eip-security-notes"></a>

* 務必在 EIP 伺服器端驗證所有參數，不僅依賴客戶端驗證
* 確保驗證 Token 有時效性限制，避免重放攻擊
* 務必使用 HTTPS 連線，保護傳輸過程中的敏感資訊
* EIP 伺服器應驗證所有接收到的參數，防止注入攻擊

## 設定欄位速查表 <a href="#settings-quick-reference" id="settings-quick-reference"></a>

| 欄位         | 必填 | 格式                   | 範例                                 |
| ---------- | -- | -------------------- | ---------------------------------- |
| 認證來源名稱     | 是  | 小寫英數 + 連字號，max 31 字元 | `company-eip`                      |
| Server URL | 是  | HTTPS URL            | `https://eip.company.com/api/auth` |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.maiagent.ai/org/sso/sso-eip.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.