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

# 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/n4T2BsxwHIraYmuaLIbG" 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 ログインは 2 種類のパスに対応しており、機能は完全に同じです。

| パス                    | 説明                     |
| --------------------- | ---------------------- |
| `/auth/eip`           | 標準パス                   |
| `/redirect/eip-login` | 互換パス。特殊なリダイレクト要件に対応します |

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

EIP 連携はロール情報の自動同期に対応しており、これは EIP の最も強力な機能の 1 つです。

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>

| 項目         | 必須 | 形式                     | 例                                  |
| ---------- | -- | ---------------------- | ---------------------------------- |
| 認証ソース名     | はい | 小文字英数字 + ハイフン、最大 31 文字 | `company-eip`                      |
| Server 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 dynamically by asking a question.

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

```
GET https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-ja/org/sso/sso-eip.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.