SAML Integration

Integrate with identity providers such as Azure AD, Okta, and Google Workspace via the SAML 2.0 protocol

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

SAML authentication settings: Fill in IdP information and the system will automatically generate SP information

After selecting the SAML 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

The SP information section provides a Copy button for convenient copying of URLs directly to the IdP configuration interface.

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 > Microsoft Entra ID > Enterprise applications

2. Click New application > Create your own application

3. Select "Integrate any other application you don't find in the gallery (Non-gallery)"

Create a custom enterprise application in Azure AD

1. Select the newly created enterprise application

Select the specified enterprise application

1. Enter the enterprise application, click Single sign-on in the left menu > SAML

Select SAML as the single sign-on method

1. In the Basic SAML Configuration 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

Fill in MaiAgent's Entity ID and ACS URL in the Basic SAML Configuration

1. Save the settings

4. Get Values from IdP and Fill Back into MaiAgent

On the Azure AD Set up SAML single sign-on 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.

Get Microsoft Entra Identifier, Login URL, and Metadata URL from Azure AD

5. Assign Users and Groups

In the Azure AD enterprise application, click Users and groups > Add user/group to add employees or groups that need access to MaiAgent.

Add employees or groups that need access to MaiAgent to the enterprise application

6. Save and Confirm

Click the Save 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

If the SAML Response does not include the displayname attribute, the system will automatically extract the Email prefix (text before @) as the display name.

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, see ADFS Integration for complete steps

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