> 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.md).

# Third-Party Login (SSO)

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.

{% hint style="info" %}
Third-Party Login (SSO) is an **Enterprise plan** exclusive feature. To enable it, contact the MaiAgent sales team to upgrade to the Enterprise plan.
{% endhint %}

## 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 <mark style="color:blue;">Organization Settings</mark> > <mark style="color:blue;">Organization Overview</mark>
2. Click the <mark style="color:blue;">Third-Party Login Settings</mark> button
3. Enter the authentication source settings page and select an authentication type

{% hint style="warning" %}
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.
{% endhint %}

## 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**](/maiagent-user-guide/maiagent-user-guide-en/org/sso/sso-saml.md)         | Integrates with SAML 2.0 identity providers (IdP)                                  | Already have Azure AD, Okta, Google Workspace, or other IdP            |
| [**EIP**](/maiagent-user-guide/maiagent-user-guide-en/org/sso/sso-eip.md)           | Enterprise Information Portal, connects to enterprise verification systems via API | Custom-built identity verification systems, flexible integration needs |
| [**Keycloak**](/maiagent-user-guide/maiagent-user-guide-en/org/sso/sso-keycloak.md) | 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](/maiagent-user-guide/maiagent-user-guide-en/org/sso/sso-saml.md)
* [EIP Integration](/maiagent-user-guide/maiagent-user-guide-en/org/sso/sso-eip.md)
* [Keycloak Integration](/maiagent-user-guide/maiagent-user-guide-en/org/sso/sso-keycloak.md)

## 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

{% hint style="info" %}
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.
{% endhint %}

## 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](/maiagent-user-guide/maiagent-user-guide-en/org/sso/sso-saml.md)         | Ends MaiAgent Session and sends an SLO request to the IdP | All integrated SPs receive logout notifications |
| [EIP](/maiagent-user-guide/maiagent-user-guide-en/org/sso/sso-eip.md)           | Ends MaiAgent Session only                                | Depends on enterprise-side configuration        |
| [Keycloak](/maiagent-user-guide/maiagent-user-guide-en/org/sso/sso-keycloak.md) | Ends MaiAgent Session + revokes Keycloak Token            | Keycloak-side Session is also terminated        |

## Permission Management

### Role Synchronization Mechanism

| Feature                        | [SAML](/maiagent-user-guide/maiagent-user-guide-en/org/sso/sso-saml.md) | [EIP](/maiagent-user-guide/maiagent-user-guide-en/org/sso/sso-eip.md) | [Keycloak](/maiagent-user-guide/maiagent-user-guide-en/org/sso/sso-keycloak.md) |
| ------------------------------ | ----------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| 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

{% hint style="info" %}
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.
{% endhint %}

### 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

{% hint style="warning" %}
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.
{% endhint %}

## 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](/maiagent-user-guide/maiagent-user-guide-en/org/role-permission.md)
* For organization management features, see [Organization Management](/maiagent-user-guide/maiagent-user-guide-en/org/organization.md)


---

# 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.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.