Keycloak Integration

Integrate with the Keycloak open-source identity verification platform via the OpenID Connect protocol

Keycloak is a widely used open-source identity verification and access management platform. MaiAgent supports integration with Keycloak via the OpenID Connect protocol.

Target audience: Enterprises using Keycloak for unified identity management, or organizations that need to manage users by Realm

Key advantages:

• Supports Keycloak Realm isolation

• Automatically synthesizes virtual Email identities for accounts without email addresses

• Supports server-side Token revocation (Logout)

• Integrates with the Keycloak ecosystem features

Setup Steps

1. Create a Client in Keycloak

1. Log in to the Keycloak Admin Console

2. Select the target Realm

3. Add a new Client under Clients

4. Set Client Protocol to openid-connect

5. Set Access Type to public (or choose confidential based on security requirements)

6. Set Valid Redirect URIs to the MaiAgent frontend domain

7. Note down the Client ID

2. Fill in Keycloak Settings in the MaiAgent Backend

After selecting the Keycloak authentication type, fill in the following fields:

Field	Required	Description
Authentication Source Name	Yes	Used as the Realm name mapping; using the Keycloak Realm name is recommended
Email Domain	Yes	The domain used for synthesizing virtual Emails, e.g., company.com
Server URL	Yes	Keycloak server URL, e.g., https://keycloak.company.com/

After completing the fields, the system will automatically generate the Login URL in the following format:

https://{frontend-domain}/auth/keycloak?url={Server URL}&clientId={Client ID}&realm={Realm}

3. Save and Test

Click Save in the MaiAgent backend, then test the login flow using the generated Login URL.

Keycloak Virtual Email Mechanism

Since Keycloak users may not have email addresses, MaiAgent automatically synthesizes a virtual Email as the unique identifier:

Virtual Email = {preferred_username}@{email_domain}

For example, the user john.doe with an Email Domain of company.com would generate [e-mail] as their MaiAgent user Email.

This virtual Email is used solely for internal system identification and will not be used for actual email delivery.

Keycloak Logout

MaiAgent's Keycloak integration supports server-side logout. When a user logs out of MaiAgent, the system simultaneously sends a Token revocation request to the Keycloak server, ensuring the Token is also invalidated on the Keycloak side.

Settings Quick Reference

Field	Required	Format	Example
Authentication Source Name	Yes	Lowercase alphanumeric + hyphens, max 31 characters	company-kc
Email Domain	Yes	Domain format	company.com
Server URL	Yes	HTTPS URL	https://keycloak.company.com/