SAML SSO Single Sign-On Integration

This document explains how the MaiAgent platform integrates the SAML 2.0 protocol to implement enterprise-grade Single Sign-On (SSO) functionality, ensuring the security and correctness of user authentication.

1. What is SAML SSO?

SAML (Security Assertion Markup Language) is an XML-based open standard for exchanging authentication and authorization data between an Identity Provider (IdP) and a Service Provider (SP).

1.1 Core Advantages of SAML SSO

Consideration	Traditional Multiple Login Approach	SAML SSO Approach
User Experience	Each system requires separate login; passwords are hard to manage	Single login grants access to multiple systems, improving productivity
Security	Passwords stored across multiple systems increase leakage risk	Passwords stored only in the enterprise IdP for centralized and more secure management
Account Management	Employee departure requires deactivating accounts in each system individually	Deactivating the account in the IdP revokes access to all systems at once
Compliance	Difficult to uniformly audit and manage access records	Centralized identity management meets enterprise security compliance requirements

1.2 Common Use Cases

• Enterprise Internal System Integration: Employees log in to MaiAgent using the company's Active Directory or Okta

• Educational Institutions: Students and faculty use the school's IdP to access AI learning assistants

• Multi-tenant SaaS: Different enterprise customers use their own IdPs to log in to the MaiAgent platform

• Partner Collaboration: Allows external partners to access specific resources using their own enterprise accounts

---

2. MaiAgent SAML SSO Architecture

2.1 Key Component Overview

• Service Provider (SP): The MaiAgent platform acts as the service provider, receiving and verifying SAML responses

• Identity Provider (IdP): The enterprise's authentication system, such as Azure AD, Okta, or Google Workspace

• SAML Assertion: An XML document signed by the IdP containing the user's identity and attribute information

• Metadata Exchange: SP and IdP exchange configuration information via XML metadata

2.2 User Attribute Mapping

MaiAgent extracts the following user attributes from the SAML Assertion:

• Email (Required): Used as the unique user identifier; the system automatically converts it to lowercase for consistency

• Name: The user's display name

• Organization Information: Department, job title, etc. (depending on IdP configuration)

• Groups/Roles: Used for permission management and access control

---

3. Email Normalization

3.1 Why is Email Normalization Needed?

Email addresses are technically case-insensitive (RFC 5321), but they may appear in different cases across different systems:

• IdP returns: [e-mail]

• User manually enters: [e-mail]

• API call: [e-mail]

Without normalization, this could lead to:

• The same user having multiple accounts created

• Incorrect permission checks

• Data inconsistency

3.2 MaiAgent's Normalization Strategy

MaiAgent implements the following Email normalization measures in its SAML SSO integration:

The system automatically strips leading and trailing whitespace from Email addresses and converts them to lowercase to ensure consistent account matching.

Normalization timing:

1. When parsing the SAML response: The user Email is converted to lowercase immediately upon receipt from the IdP

2. When creating an account: Email is ensured to be lowercase before creating a new user account

3. When querying accounts: Lowercase Email is used when looking up existing users

4. When storing in the database: All stored Emails are maintained in lowercase format

3.3 Backward Compatibility Handling

For accounts created before the normalization mechanism was implemented, MaiAgent adopts the following strategy:

• Automatic Migration: The system automatically converts existing account Emails to lowercase

• Duplicate Detection: Checks for duplicate accounts during the conversion process

• Conflict Resolution: If conflicts are detected, the earliest created account is retained and data is merged

---

4. Automatic Account Creation and Account Conflict Handling

4.1 Automatic Account Creation Flow

When a user logs in via SAML SSO for the first time, MaiAgent automatically creates an account:

Default settings for automatic creation:

• Display Name: Extracted from the name attribute in the SAML Assertion

• Default Permissions: Basic permissions assigned based on organization settings

• Organization Affiliation: Determined by Email domain or IdP configuration

4.2 Handling Existing Accounts

MaiAgent implements an intelligent account conflict detection and handling mechanism:

• Email Already Registered: If a user has previously registered with the same Email (lowercase), they are logged in to the existing account

• Notification Email: When an existing account is detected, a notification email is sent to the user

• Prevent Duplicate Creation: Database unique constraints ensure the same Email cannot create multiple accounts

4.3 Security Considerations

• Email Verification: Trusts the Email provided by the IdP since it has already been verified through enterprise identity authentication

• SAML Signature Verification: Strictly verifies the digital signature of the SAML Response to prevent forgery

• Timestamp Validation: Ensures the SAML Assertion has not expired

• Replay Attack Protection: Records used SAML Response IDs to prevent reuse

---

5. SAML SSO Configuration Steps

5.1 Configuration on the IdP Side

Enterprise IT administrators need to configure the following in the IdP (such as Okta, Azure AD):

1. Create a new SAML application

2. Set MaiAgent's ACS URL (Assertion Consumer Service URL)

3. Configure user attribute mappings, ensuring Email is included

4. Download the IdP Metadata XML and provide it to MaiAgent

5.2 Configuration on the MaiAgent Side

MaiAgent administrators need to:

1. Upload the IdP Metadata XML to the MaiAgent admin panel

2. Set the Entity ID to identify this SAML integration

3. Configure attribute mapping rules for fields such as Email and name

4. Enable SAML SSO and test the login flow

5.3 Testing and Verification

After configuration is complete, the following tests are recommended:

• First Login Test: Verify that automatic account creation works correctly

• Repeat Login Test: Verify that logging in with an existing account works

• Email Case Test: Verify that Emails in different cases are correctly recognized

• Logout Test: Verify that Single Logout (SLO) functionality works correctly

---

6. Technical Advantages of MaiAgent SAML SSO

6.1 Security Advantages

• Enterprise-grade Authentication: Leverages the enterprise's existing identity management system to ensure consistent authentication standards

• Passwords Never Pass Through MaiAgent: User passwords are only verified within the enterprise IdP, reducing leakage risk

• Centralized Access Control: IT administrators can manage access permissions for all applications from a single IdP

• Enforced Multi-factor Authentication: If the IdP has MFA enabled, users logging in to MaiAgent will also be required to complete MFA

6.2 Management Efficiency Advantages

• Automatic Account Creation: Reduces the operational burden of manually creating accounts

• Automatic Account Deactivation: When an employee leaves and their IdP account is deactivated, MaiAgent access is immediately revoked

• Attribute Synchronization: User name, department, and other information changes are automatically synced

• Audit Records: All login activities have complete records for security auditing

6.3 User Experience Advantages

• Seamless Login: If the user is already logged in to the enterprise system, they may not need to enter a password again when accessing MaiAgent

• Unified Login Interface: Uses the familiar enterprise login page without requiring additional passwords

• Mobile Friendly: Supports SSO experience on mobile devices

---

7. Troubleshooting

7.1 Common Issues

Issue	Possible Cause	Solution
Unable to Log In	SAML signature verification failed	Verify that the IdP certificate has not expired and the Metadata is up to date
Duplicate Account Created	Email case inconsistency	Ensure the system has the Email normalization fix applied
Missing Attributes	IdP did not send required attributes	Check the IdP's attribute mapping configuration and ensure Email is included
Timestamp Error	Server time out of sync	Ensure SP and IdP system times are synchronized (NTP recommended)

7.2 Debugging Tools

• SAML-tracer: A browser extension for capturing and analyzing SAML messages

• MaiAgent Logs: View detailed SAML processing logs

• IdP Admin Console: Check error logs and user attributes on the IdP side

---

8. Related Documentation

• Organization and Member Management - Learn about permission management for SAML users

• Third-party Login (SSO) - SSO configuration instructions in the user guide

Reference Links

• SAML 2.0 Technical Overview

• SAML Security Best Practices