EIP Integration

Integrate with your enterprise's existing identity verification system through EIP, with flexible parameter passing and automatic role synchronization

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 EIP 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:

{
  "email": "[e-mail]",
  "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

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.

4. Save Settings

After confirming the test passes, click Save 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

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.

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.

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