> 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/maiagent-user-guide/ja/org/sso/sso-eip.md).

# EIP 連携

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>

認証タイプとして <mark style="color:blue;">EIP</mark> を選択した後、次の項目を入力します。

| 項目                                        | 必須 | 説明                                                              |
| ----------------------------------------- | -- | --------------------------------------------------------------- |
| <mark style="color:blue;">認証ソース名</mark>   | はい | 認証ソースの英字の識別名です。例：`company-eip`                                  |
| <mark style="color:blue;">サーバー URL</mark> | はい | EIP サーバーの認証 API エンドポイントです。例：`https://eip.internal.com/api/auth` |

入力が完了すると、システムが次の形式で **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（UUID）の一覧です。MaiAgent のロールを自動同期するために使用します。[ロールの自動同期](#role-auto-sync)を参照してください |

### 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` フィールドで指定できます

## ログイン失敗時のメッセージ <a href="#error-messages" id="error-messages"></a>

ユーザーが EIP から MaiAgent にリダイレクトされると、画面にはまず「EIP ログイン中...」と表示されます。失敗した場合は、下に赤字で原因が表示されます。

| 画面のメッセージ                                        | よくある原因                                          | 対処方法                                                                                              |
| ----------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| 缺少必要的參數 (serverUrl)（必須パラメータ (serverUrl) がありません） | リダイレクト先 URL に `serverUrl` パラメータがありません           | EIP 側で生成しているリダイレクト先 URL を確認してください。`serverUrl` は EIP の認証エンドポイントを指している必要があります                       |
| API 登入失敗（API ログインに失敗しました）                       | MaiAgent が EIP サーバーで検証した後、有効なユーザーデータを取得できませんでした | EIP 側が[EIP サーバーを設定する](#step-2-configure-eip-server)のとおりに `email`、`name` などのフィールドを返していることを確認してください |
| API 登入過程發生錯誤（API ログイン処理中にエラーが発生しました）            | MaiAgent が `serverUrl` に接続できないか、EIP がエラーを返しました  | MaiAgent サーバーから EIP の認証エンドポイントに接続できること（ファイアウォール、証明書）を確認し、そのうえで EIP 側のエラーログを確認してください               |

## EIP のリダイレクトパス <a href="#eip-redirect-path" id="eip-redirect-path"></a>

EIP ログインは 2 種類のパスに対応しており、機能は完全に同じで、クエリパラメータの使い方も同じです。

| パス                   | 説明                                               |
| -------------------- | ------------------------------------------------ |
| `/auth/eip`          | 標準パス                                             |
| `/auth/eip/redirect` | 互換パス。EIP 側のリダイレクト先が `redirect` で終わる必要がある場合に使用します |

## ロールの自動同期 <a href="#role-auto-sync" id="role-auto-sync"></a>

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 のセキュリティに関する注意事項 <a href="#eip-security-notes" id="eip-security-notes"></a>

* すべてのパラメータは必ず EIP サーバー側で検証し、クライアント側の検証だけに依存しないでください
* 認証トークンには有効期限を設け、リプレイ攻撃を防いでください
* 必ず HTTPS 接続を使用し、通信中の機密情報を保護してください
* EIP サーバーは、受信したすべてのパラメータを検証し、インジェクション攻撃を防ぐ必要があります

## 設定項目クイックリファレンス <a href="#settings-quick-reference" id="settings-quick-reference"></a>

| 項目       | 必須 | 形式                     | 例                                  |
| -------- | -- | ---------------------- | ---------------------------------- |
| 認証ソース名   | はい | 小文字英数字 + ハイフン、最大 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/maiagent-user-guide/ja/org/sso/sso-eip.md?ask=<question>&goal=<user_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.
