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

# SAML Integration

SAML (Security Assertion Markup Language) is a standard authentication protocol widely adopted by enterprise-grade applications.

**Target audience**: Enterprises with existing SAML identity providers (such as Microsoft Entra ID / Azure AD, Okta, Google Workspace)

**Key advantages**:

* Industry-standard protocol with high compatibility
* Supports complete user attribute passing
* Integrates with multi-factor authentication (MFA)
* Supports Single Logout (SLO)

## Setup Steps

### 1. Fill in IdP Information in the MaiAgent Backend

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

| Field                      | Required | Description                                           |
| -------------------------- | -------- | ----------------------------------------------------- |
| Authentication Source Name | Yes      | Used to generate SP endpoint URLs, e.g., `my-company` |
| IdP Metadata URL           | Yes      | The identity provider's metadata URL                  |
| IdP Entity ID              | Yes      | The identity provider's entity identifier             |
| IdP SSO URL                | Yes      | The identity provider's single sign-on endpoint URL   |
| Email Domain               | No       | Optional enterprise Email domain                      |

### 2. Obtain SP (MaiAgent Side) Information

After filling in the authentication source name, the system automatically generates the following SP information, displayed on the settings page:

| SP Field                                 | Format                                            | Description                       |
| ---------------------------------------- | ------------------------------------------------- | --------------------------------- |
| Entity ID                                | `https://{domain}/accounts/saml/{name}/metadata/` | Provided to IdP for configuration |
| ACS URL (Assertion Consumer Service URL) | `https://{domain}/accounts/saml/{name}/acs/`      | Provided to IdP for configuration |
| Login URL                                | `https://{API-domain}/auth/saml/{name}/login/`    | SAML login entry point            |

{% hint style="info" %}
The SP information section provides a <mark style="color:blue;">Copy</mark> button for convenient copying of URLs directly to the IdP configuration interface.
{% endhint %}

### 3. Configure the MaiAgent Application in the Identity Provider (IdP)

Using **Microsoft Entra ID (Azure AD)** as an example:

1. Log in to [Azure Portal](https://portal.azure.com/) > <mark style="color:blue;">Microsoft Entra ID</mark> > <mark style="color:blue;">Enterprise applications</mark>
2. Click <mark style="color:blue;">New application</mark> > <mark style="color:blue;">Create your own application</mark>
3. Select "**Integrate any other application you don't find in the gallery (Non-gallery)**"
4. Select the newly created enterprise application
5. Enter the enterprise application, click <mark style="color:blue;">Single sign-on</mark> in the left menu > <mark style="color:blue;">SAML</mark>
6. In the <mark style="color:blue;">Basic SAML Configuration</mark> section, fill in MaiAgent's SP information:
   * **Identifier (Entity ID)**: Enter the Entity ID generated by MaiAgent
   * **Reply URL (Assertion Consumer Service URL)**: Enter the ACS URL generated by MaiAgent
7. Save the settings

### 4. Get Values from IdP and Fill Back into MaiAgent

On the Azure AD <mark style="color:blue;">Set up SAML single sign-on</mark> page, find the following information at the bottom:

| Azure AD Field              | Corresponding MaiAgent Field |
| --------------------------- | ---------------------------- |
| App Federation Metadata URL | IdP Metadata URL             |
| Microsoft Entra Identifier  | IdP Entity ID                |
| Login URL                   | IdP SSO URL                  |

Fill these values into the SAML settings form in the MaiAgent backend.

### 5. Assign Users and Groups

In the Azure AD enterprise application, click <mark style="color:blue;">Users and groups</mark> > <mark style="color:blue;">Add user/group</mark> to add employees or groups that need access to MaiAgent.

### 6. Save and Confirm

Click the <mark style="color:blue;">Save</mark> button in the MaiAgent backend. The system will display a confirmation dialog reminding you that:

* After switching the authentication type, the employee login method will change
* Existing users need to use the new SSO method to log in
* Ensure the IdP-side configuration is complete

Confirm to complete the setup.

## SAML Attribute Mapping

MaiAgent extracts the following attributes from the SAML Response:

| SAML Attribute (Claim)                                       | MaiAgent Field | Description                                 |
| ------------------------------------------------------------ | -------------- | ------------------------------------------- |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` | User Email     | Required field, used as user identification |
| `http://schemas.microsoft.com/identity/claims/displayname`   | Display Name   | Username displayed in the interface         |

{% hint style="info" %}
If the SAML Response does not include the displayname attribute, the system will automatically extract the Email prefix (text before @) as the display name.
{% endhint %}

## Other SAML IdP Configurations

MaiAgent's SAML integration is not limited to Microsoft Entra ID. Any identity provider that supports the SAML 2.0 standard protocol can be integrated. Common IdPs include:

* **Okta**: Add a SAML 2.0 App under Applications
* **Google Workspace**: Configure in Admin Console > Security > SSO
* **ADFS**: Add under Relying Party Trusts

The configuration logic is the same: Fill MaiAgent's SP information (Entity ID, ACS URL) into the IdP, then fill the IdP's information (Metadata URL, Entity ID, SSO URL) back into MaiAgent.

## SAML Security Features

* Supports SAML 2.0 HTTP Redirect Binding
* Session Index tracking ensures correct logout operations
* NameID format uses emailAddress to ensure consistent user identification
* Login Cookie settings: `Secure=True`, `SameSite=None`, `HttpOnly=True`, with a 5-minute validity period

## Settings Quick Reference

| Field                      | Required | Format                                              | Example                                                                                   |
| -------------------------- | -------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Authentication Source Name | Yes      | Lowercase alphanumeric + hyphens, max 31 characters | `my-company`                                                                              |
| IdP Metadata URL           | Yes      | HTTPS URL                                           | `https://login.microsoftonline.com/.../federationmetadata/2007-06/federationmetadata.xml` |
| IdP Entity ID              | Yes      | URI                                                 | `https://sts.windows.net/{tenant-id}/`                                                    |
| IdP SSO URL                | Yes      | HTTPS URL                                           | `https://login.microsoftonline.com/{tenant-id}/saml2`                                     |
| Email Domain               | No       | Domain format                                       | `company.com`                                                                             |


---

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