> 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-en/org/sso/sso-eip.md).

# EIP Integration

EIP (Enterprise Information Portal) provides a flexible enterprise integration solution by connecting to your existing identity verification system via API.

**Target audience**: Enterprises with custom-built identity verification systems, or organizations requiring customized integration logic

**Key advantages**:

* Simplified integration process
* Flexible parameter passing, not limited to fixed parameter names
* Integration methods can be adapted to enterprise requirements
* Supports automatic role information synchronization

## Setup Steps

### 1. Fill in EIP Settings in the MaiAgent Backend

After selecting the <mark style="color:blue;">EIP</mark> authentication type, fill in the following fields:

| Field                      | Required | Description                                                           |
| -------------------------- | -------- | --------------------------------------------------------------------- |
| Authentication Source Name | Yes      | English identifier for the authentication source, e.g., `company-eip` |
| Server URL                 | Yes      | The verification API endpoint of the EIP server                       |

After completing the fields, the system will automatically generate the **Login URL** in the following format:

```
https://{frontend-domain}/auth/eip?serverUrl={EIP-server-URL}
```

### 2. Configure the EIP Server

Ensure your EIP server has the following capabilities:

1. Receive payload parameters sent by MaiAgent (supports both GET and POST methods)
2. Verify user identity based on the payload content
3. Return user information in the following format:

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

| Response Field | Required | Description                                                                            |
| -------------- | -------- | -------------------------------------------------------------------------------------- |
| `email`        | Yes      | User email, used as the unique identifier                                              |
| `name`         | No       | User display name                                                                      |
| `groupIds`     | No       | List of role IDs the user belongs to, used for automatic MaiAgent role synchronization |

### 3. Test the Login Flow

Test using the Login URL with parameters generated by the EIP system:

```
# Example 1: Including SessionId (legacy compatibility)
https://{frontend-domain}/auth/eip?serverUrl=https://eip.company.com&sessionId=abc123

# Example 2: Without SessionId (new version support)
https://{frontend-domain}/auth/eip?serverUrl=https://eip.company.com&userId=12345&token=xyz789

# Example 3: Custom parameters
https://{frontend-domain}/auth/eip?serverUrl=https://eip.company.com&customParam1=value1&customParam2=value2
```

{% hint style="info" %}
`sessionId` is optional in the latest version. The system automatically collects all query parameters from the URL except `serverUrl` as the payload, which is sent to the EIP server for verification.
{% endhint %}

### 4. Save Settings

After confirming the test passes, click <mark style="color:blue;">Save</mark> in the MaiAgent backend to complete the setup.

## EIP Parameter Handling Logic

When MaiAgent receives an EIP login request, it processes parameters as follows:

1. Separates the `serverUrl` parameter
2. Collects all other query parameters as the `payload` object
3. Appends fixed parameters (`op=maiagent`, `type=json`) to the `payload` and sends it to the EIP server
4. The EIP server supports both GET and POST receiving methods; you can specify the method via the `method` field in the payload

## EIP Redirect Paths

EIP login supports two paths with identical functionality:

| Path                  | Description                                                    |
| --------------------- | -------------------------------------------------------------- |
| `/auth/eip`           | Standard path                                                  |
| `/redirect/eip-login` | Compatibility path, suitable for special redirect requirements |

## Automatic Role Synchronization

EIP integration supports automatic role information synchronization, which is one of EIP's most powerful features:

1. The enterprise includes a `groupIds` role list in the user information returned by EIP
2. MaiAgent automatically assigns users to corresponding roles upon receiving this information
3. Uses a **full replacement strategy**: The roles returned by EIP take precedence, removing old roles not in the list
4. Synchronization occurs on every login, ensuring permissions remain consistent with the enterprise side

{% hint style="warning" %}
Role synchronization uses a full replacement strategy, meaning the role list returned by EIP will completely overwrite the user's role assignments in MaiAgent. Ensure the role list returned by the EIP side is complete.
{% endhint %}

{% hint style="info" %}
If `groupIds` contains role IDs that have not yet been created in MaiAgent, the system will return a verification error. Create the corresponding roles in MaiAgent in advance.
{% endhint %}

## EIP Security Considerations

* Always validate all parameters on the EIP server side; do not rely solely on client-side validation
* Ensure verification tokens have time-based expiration to prevent replay attacks
* Always use HTTPS connections to protect sensitive information during transmission
* The EIP server should validate all received parameters to prevent injection attacks

## Settings Quick Reference

| Field                      | Required | Format                                              | Example                            |
| -------------------------- | -------- | --------------------------------------------------- | ---------------------------------- |
| Authentication Source Name | Yes      | Lowercase alphanumeric + hyphens, max 31 characters | `company-eip`                      |
| Server URL                 | Yes      | 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-en/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.