> 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/en/org/sso/sso-keycloak.md).

# 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 <a href="#setup-steps" id="setup-steps"></a>

### 1. Create a Client in Keycloak <a href="#step-1-create-client" id="step-1-create-client"></a>

1. Log in to the Keycloak Admin Console
2. Select the target Realm
3. Add a new Client under <mark style="color:blue;">Clients</mark>
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 <a href="#step-2-fill-keycloak-settings" id="step-2-fill-keycloak-settings"></a>

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

| Field                                                       | Required | Description                                                                                                                      |
| ----------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">Authentication Source Name</mark> | Yes      | The English identifier of this authentication source. It becomes part of the login link, e.g., `company-kc`                      |
| <mark style="color:blue;">Virtual Email Domain</mark>       | Yes      | The domain used to synthesize virtual Emails. The system generates user emails as "account\@this-domain", e.g., `company.com`    |
| <mark style="color:blue;">Server URL</mark>                 | Yes      | Keycloak server URL, e.g., `https://keycloak.company.com/`                                                                       |
| <mark style="color:blue;">Realm Name</mark>                 | Yes      | The name of the Realm your organization uses in Keycloak. It is combined into the `realm` parameter of the login link            |
| <mark style="color:blue;">Client ID</mark>                  | Yes      | The Client ID of the OIDC Client created in that Realm in step 1. It is combined into the `clientId` parameter of the login link |

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 <a href="#step-3-save-and-test" id="step-3-save-and-test"></a>

Click <mark style="color:blue;">Save</mark> in the MaiAgent backend, then test the login flow using the generated Login URL.

## Keycloak Virtual Email Mechanism <a href="#keycloak-virtual-email-mechanism" id="keycloak-virtual-email-mechanism"></a>

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 a Virtual Email Domain of `company.com` would generate `john.doe@company.com` as their MaiAgent user Email.

{% hint style="info" %}
This virtual Email is used only for internal system identification and is never used to send actual emails.
{% endhint %}

## Login Failure Messages <a href="#error-messages" id="error-messages"></a>

After a user opens the Keycloak login link, the screen first shows "Keycloak login in progress..."; if it fails, the reason is shown below in red text:

| On-screen message                                                                   | Common cause                                                                                                                           | Resolution                                                                                                                                                                                                               |
| ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 缺少必要的參數 (url, clientId, realm) (Missing required parameters (url, clientId, realm)) | The opened URL is missing the Keycloak server, Client ID, or Realm parameter, usually because the link was truncated or edited by hand | Use the complete URL copied from the login link card on the settings page                                                                                                                                                |
| 認證過程發生錯誤，請重試（…） (An error occurred during authentication, please retry (…))         | The browser cannot reach the Keycloak server, or the Client settings (Valid redirect URIs, Web origins) do not allow the MaiAgent URL  | Confirm the user's network can reach Keycloak; check the Client's redirect URI and Web origins settings                                                                                                                  |
| API 登入失敗 (API login failed)                                                         | Keycloak verification succeeded, but MaiAgent did not return a login result                                                            | Confirm that login is enabled for this authentication source in the backend, then try again                                                                                                                              |
| API 登入過程發生錯誤（…） (An error occurred during API login (…))                            | An error occurred while MaiAgent was verifying the Keycloak Token; the reason returned by the server is in parentheses                 | Handle it according to the message in parentheses; commonly, the server URL, Realm name, or Client ID in the link does not match the backend settings, or the authentication source does not belong to this organization |

## Keycloak Logout <a href="#keycloak-logout" id="keycloak-logout"></a>

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

## Settings Quick Reference <a href="#settings-quick-reference" id="settings-quick-reference"></a>

| Field                      | Required | Format                                                    | Example                         |
| -------------------------- | -------- | --------------------------------------------------------- | ------------------------------- |
| Authentication Source Name | Yes      | Lowercase letters and digits + hyphens, max 31 characters | `company-kc`                    |
| Virtual Email Domain       | Yes      | Domain format                                             | `company.com`                   |
| Server URL                 | Yes      | HTTPS URL                                                 | `https://keycloak.company.com/` |
| Realm Name                 | Yes      | Keycloak Realm name                                       | `company-sso`                   |
| Client ID                  | Yes      | Client ID of the Keycloak OIDC Client                     | `maiagent-portal`               |


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/maiagent-user-guide/en/org/sso/sso-keycloak.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.