Third-Party Login (SSO)

Configure enterprise SSO integration (SAML / EIP / Keycloak) to let employees log in to MaiAgent using company accounts

Enterprise Single Sign-On (SSO) allows your employees to log in to the MaiAgent platform using your company's existing account system, eliminating the need to memorize additional usernames and passwords. By integrating with your enterprise identity verification system, employees only need to log in once to the company system to seamlessly access all MaiAgent features, greatly simplifying the login process and enhancing security.

Third-Party Login (SSO) is an Enterprise plan exclusive feature. To enable it, contact the MaiAgent sales team to upgrade to the Enterprise plan.

Use Cases

1. Large enterprise deployment: A company with 100+ employees who need to use MaiAgent; SSO integration avoids creating accounts one by one

2. Unified permission management: Centrally manage all employee roles and permissions through the company's identity verification system

3. Security requirements: Industries with high security standards such as finance and healthcare require employees to pass enterprise authentication for all system access

4. Multi-system integration: The company already uses multiple SaaS services and wants employees to log in to all systems with one set of credentials

5. Offboarding management: When an employee leaves, simply disabling their account on the enterprise side simultaneously revokes MaiAgent access permissions

Accessing Third-Party Login Settings

1. From the left menu, click Organization Settings > Organization Overview

2. Click the Third-Party Login Settings button

3. Enter the authentication source settings page and select an authentication type

Only the organization's Owner has permission to modify third-party login settings. If you do not see the settings button, verify your role permissions.

Supported Authentication Types

MaiAgent provides 4 authentication methods. Choose the best option based on your enterprise needs:

Authentication Type	Description	Use Case
MaiAgent (Default)	Uses MaiAgent's built-in username and password	Small teams, no enterprise SSO requirement
SAML	Integrates with SAML 2.0 identity providers (IdP)	Already have Azure AD, Okta, Google Workspace, or other IdP
EIP	Enterprise Information Portal, connects to enterprise verification systems via API	Custom-built identity verification systems, flexible integration needs
Keycloak	Integrates with the Keycloak open-source identity verification platform	Enterprises using Keycloak for unified identity management

After entering the settings page, 4 authentication type cards are displayed. The currently active authentication type is marked with a green "Active" badge. Click on the target authentication type to expand its settings form.

For detailed setup steps for each authentication type, see:

• SAML Integration

• EIP Integration

• Keycloak Integration

Authentication Source Name Rules

Regardless of which third-party authentication type you choose, you need to set an Authentication Source Name. This name follows these rules:

• Only lowercase letters, numbers, hyphens (-), and underscores (_) are allowed

• Maximum 31 characters

• Must be unique across the entire system (case-insensitive)

• The reserved name maiagent cannot be used

The authentication source name is used as part of system URLs (such as SAML Entity ID and ACS URL). If changes are needed after setup, the identity provider-side configuration must also be updated. Using your company's English abbreviation as the name is recommended.

User Login Flow

First Login

When an employee first logs in to MaiAgent via SSO:

1. Click the SSO login link (Login URL)

2. The system redirects to the enterprise identity verification page (IdP / EIP / Keycloak)

3. Complete identity verification on the enterprise side

4. After successful verification, automatically redirected back to MaiAgent

5. The system automatically creates the employee's MaiAgent account, setting the display name and authentication source

6. If role information is available (EIP), the corresponding roles and permissions are automatically applied

7. The employee enters the MaiAgent admin backend

Subsequent Logins

1. If the enterprise system's Session is still valid, the user may enter MaiAgent directly (depending on IdP settings)

2. If the Session has expired, re-verification on the enterprise side is required

3. User information (name, authentication source) is automatically updated on each login

4. EIP login synchronizes role assignments

Logout Behavior

Authentication Type	When Logging Out of MaiAgent	When Logging Out of Enterprise Side
SAML	Ends MaiAgent Session and sends an SLO request to the IdP	All integrated SPs receive logout notifications
EIP	Ends MaiAgent Session only	Depends on enterprise-side configuration
Keycloak	Ends MaiAgent Session + revokes Keycloak Token	Keycloak-side Session is also terminated

Permission Management

Role Synchronization Mechanism

Feature	SAML	EIP	Keycloak
Automatic user creation	On first login	On first login	On first login
Automatic role synchronization	Not supported	Supported (on each login)	Not supported
Sync strategy	-	Full replacement	-
Role source	Manual assignment in MaiAgent	groupIds returned by EIP	Manual assignment in MaiAgent

Additional MaiAgent-Side Configuration

Regardless of which SSO authentication type is used, MaiAgent administrators can:

1. Configure accessible AI assistants, knowledge bases, and other resources for synced roles

2. Adjust role permission scopes

3. Manually add additional MaiAgent local roles for users

When using EIP's automatic role synchronization, create and configure role permissions in MaiAgent in advance so employees inherit the correct permissions immediately upon login.

Permission Update Timing

Timing	Description
Each SSO login	Updates username, authentication source; EIP syncs roles
Manual adjustment	Administrator manually modifies role assignments in MaiAgent backend

Switching Authentication Types

MaiAgent supports switching between different authentication types. Please note the following when switching:

Switching from MaiAgent to Third-Party Authentication

• The system creates a new authentication source configuration

• Existing users' authentication sources are not immediately changed; they update automatically the next time they log in using the new SSO method

• The organization is marked as the default organization for that authentication source

Switching from Third-Party Authentication Back to MaiAgent

• All users created through SSO are redirected to MaiAgent default authentication

• The old third-party authentication source configuration is deleted

• Users need to log in with MaiAgent username and password (may need to reset passwords)

Switching Between Third-Party Authentication Types

• The old authentication configuration is cleared and the new configuration is applied

• Users need to log in using the new SSO method

Switching authentication types is a major operation. Ensure the new authentication configuration has been completed and tested on the enterprise side before executing. The system will display a confirmation dialog when saving — read the reminders carefully.

Security Considerations

Transport Security

• All authentication flows use HTTPS encrypted transmission

• SAML responses support XML signature verification

• Keycloak integration uses JWT Token verification

• MaiAgent does not store enterprise-side passwords

Access Control

• Only employees who pass enterprise verification can log in via SSO

• When an employee leaves, disabling their account on the enterprise side revokes MaiAgent access

• Authentication source configuration is restricted to organization owners

• Third-party authentication features require the Enterprise plan

Troubleshooting

Login Failure

Issue: Error message appears after clicking SSO login

Possible Cause	Solution
Incorrect IdP / EIP configuration	Verify the URLs entered in the MaiAgent backend are correct
SP information not correctly configured in IdP	Confirm Entity ID and ACS URL have been correctly entered in the IdP
User not assigned to the enterprise application	Add the user to the application's user list on the IdP side
SAML Response missing Email attribute	Confirm the IdP is configured to send the Email Claim
Authentication source name mismatch	Confirm the name set in MaiAgent matches the name in the URL
Not on Enterprise plan	Confirm the organization has been upgraded to the Enterprise plan

Roles Not Syncing Correctly (EIP)

Issue: Expected role permissions not present after login

1. Verify the groupIds content returned by the EIP server is correct

2. Confirm the role IDs in groupIds have been created in MaiAgent

3. Confirm groupIds does not include DEFAULT type roles (the system applies these automatically)

4. Try logging out and logging back in

User Information Not Updated

Issue: MaiAgent still shows old data after updating information on the enterprise side

1. Log out of MaiAgent and log back in (SSO login automatically updates information)

2. Clear browser cache

3. Confirm the IdP / EIP side is correctly returning the latest user information

Settings Page Shows "Enterprise Plan Exclusive Feature"

Issue: Cannot see the authentication type settings form

This feature requires the Enterprise plan. Contact the MaiAgent sales team to upgrade your plan.

Unable to Save Settings

Issue: Error displayed after clicking Save

1. Confirm all required fields have been filled in

2. Confirm the authentication source name meets format requirements (lowercase alphanumeric + hyphens)

3. Confirm the authentication source name does not duplicate another organization's name

4. Confirm URL fields are in the correct format (include https://)

FAQ

Q: How long does SSO integration take? A: Configuration in the MaiAgent backend can be completed instantly. The overall time depends on enterprise-side preparation. If enterprise-side information is ready, integration and testing can typically be completed within a few hours.

Q: After enabling SSO, can existing regular accounts still be used? A: Yes. Enabling SSO does not automatically disable regular account login. However, for security reasons, discuss with the MaiAgent team whether to disable regular login.

Q: Do I need to manually delete accounts in MaiAgent after an employee leaves? A: No. Simply disabling the employee's account on the enterprise side prevents them from logging in to MaiAgent via SSO.

Q: Can some employees use SSO while others use regular credentials? A: Yes. The system supports mixed login modes. For example, full-time employees use SSO while external consultants use regular username and password.

Q: Does SSO integration cost extra? A: SSO integration is an Enterprise plan feature. If your plan already includes enterprise features, no additional fees are required. Contact the sales team for detailed plan information.

Q: Can one organization set up multiple SSO methods simultaneously? A: Currently, each organization can only configure one authentication type. To switch, change it directly in the backend.

Q: How does EIP role synchronization work? A: When logging in via EIP, the system reads the role list (groupIds) returned by EIP and automatically syncs it to MaiAgent. Synchronization occurs on every login using a full replacement strategy (EIP's returned roles take precedence), ensuring permissions remain consistent with the enterprise side.

Q: Will the virtual Email in Keycloak integration be used to send actual emails? A: No. The virtual Email ({username}@{email_domain}) is used solely as a unique user identifier within the MaiAgent system and will not be used for actual email delivery.

Q: How do I verify that SAML SP information is correct? A: After filling in the authentication source name in the MaiAgent backend, the SP information (Entity ID, ACS URL) is automatically displayed on the settings page, ready for you to copy and use.

Further Reading

• For detailed role permission settings, see Role Permission Management

• For organization management features, see Organization Management