---
title: "Rocket Chat Authentication with Keycloak"
slug: "keycloak"
description: "Configure Keycloak for Rocket Chat authentication. Ensure secure access, regulatory compliance, and identity federation."
updated: 2026-10-26T16:55:17Z
published: 2026-10-26T16:55:17Z
canonical: "docs.rocket.chat/keycloak"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rocket.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Keycloak - SAML Setup Example

![](https://cdn.us.document360.io/6ae79a05-7252-45d0-96e8-8f375e07b1b2/Images/Documentation/Premium(11).svg)

> [!WARNING]
> From Rocket.Chat 9.0.0, SAML is available on Starter workspaces and on all premium plans (Commercial, Government, and Defense). It is not available on Community workspaces. See [Our Plans](/v1/docs/our-plans) for details.

## Prerequisites

- A Rocket.Chat workspace (e.g., `https://test-rocket.chat`).
- A Keycloak server (e.g., `https://keycloak.test.com`).
- A Keycloak [realm](https://www.keycloak.org/docs/latest/server_admin/#configuring-realms) set up for use (e.g., `master`). This guide references the realm using the placeholder `<realm>`.
- Your Keycloak realm must have the SAML identity provider and the RS256 algorithm configured as the keystore provider.

## Set up Keycloak in Rocket.Chat

To begin, configure Keycloak in your Rocket.Chat workspace. Follow these steps in the [SAML configuration](/v1/docs/saml-configuration) section of Rocket.Chat settings:

1. Go to **Manage** ![Screenshot 2025-12-23 130522.png](https://cdn.us.document360.io/6ae79a05-7252-45d0-96e8-8f375e07b1b2/Images/Documentation/Screenshot%202025-12-23%20130522.png) **→ Workspace → Settings → SAML**.
2. **Enable** the **SAML connection** in Rocket.Chat.
3. Set the **Custom Provider** to `keycloak`.
4. Configure the **Custom Entry Point** and **IDP SLO Redirect URL:**
  1. In your Keycloak server, go to **Realm Settings**.
  2. Under the **General** tab, select **SAML 2.0 Identity Provider Metadata** from the **Endpoints** section. This will open an XML file containing the necessary URLs.
  3. Copy the appropriate URL, such as `https://<your-keycloak-server>/realms/<realm>/protocol/saml`, and paste it into both the **Custom Entry Point** and **IDP SLO Redirect URL** fields in Rocket.Chat.
5. **Set the Custom Issuer** to `https://<your-workspace>/_saml/metadata/keycloak`.

### Configure certificates

To ensure secure communication between Keycloak and Rocket.Chat, configure the required [certificates](/v1/docs/saml-configuration#certificate) under Rocket.Chat SAML settings:

1. **Obtain the RS256 certificate**:
  1. In Keycloak, navigate to **Realm Settings** and open the **Keys** tab.
  2. Copy the **RS256 certificate** and paste it into the **Custom Certificate** field in Rocket.Chat.
2. **Generate a certificate pair** for Rocket.Chat:

```bash
openssl req -newkey rsa:3072 -new -x509 -days 3652 -nodes -out saml.crt -keyout saml.pem
```
  - Run the following OpenSSL command to generate a public certificate and a private key:
  1. This command creates two files:
    - **saml.crt**: The public certificate.
    - **saml.pem**: The private key.
  2. Copy the contents of these files and update the respective fields in Rocket.Chat:
    1. **Public Cert Contents**: Paste the contents of `saml.crt`.
    2. **Private Key Contents**: Paste the contents of `saml.pem`.
3. Set the **Signature Validation Type** to **Validate Either Signature**.
4. Click **Save Changes**.

## Configure Keycloak client

After setting up SAML in Rocket.Chat, the next step is to configure a Keycloak client that will handle authentication between users on your Keycloak server and Rocket.Chat workspace. This client will manage the exchange of user information, allowing users to authenticate securely on Rocket.Chat using their Keycloak credentials.

Follow the steps below to configure the Keycloak client:

**Download the SAML metadata XML file**

1. Go to `https://<workspace-url>/_saml/metadata/keycloak`. You’ll get an XML file. Ensure SAML is enabled in your Rocket.Chat workspace to access this file.
2. Save the raw XML file to your device.

**Import the client in Keycloak**

1. Navigate to the **Clients** section in your Keycloak server.
2. Click **Import Client** and upload the XML file you saved as the **Resource file**.
3. The client **Type** will be set to `saml`, and the **ClientID** will be populated based on the metadata URL.
4. Enable **Client Signature Required**.
5. Click **Save** to create the new client. You will be redirected to a partially pre-filled client settings page.

**Configure the client settings**

1. Ensure the **Client ID** matches the metadata URL.
2. Verify the **Valid Redirect URIs** field is set to `https://<workspace-url>/_saml/validate/keycloak`.
3. Set the **Name ID Format** to `email`.
4. Set **SAML signature key name** to `KEY_ID`.
5. Click **Save**.

**Verify the public key (certificate)**

1. Go to the **Keys** tab in the client and verify that the public key matches the **Public Cert Contents** you set in Rocket.Chat SAML settings.

> [!NOTE]
> The `-----BEGIN/END CERTIFICATE-----` header/footer is not displayed in Keycloak, but the rest of the certificate should match.
2. If the certificates do not match, click **Import Key**. Select **Certificate PEM** as the archive format and upload the `saml.crt` certificate file generated earlier. Then, click **Import**.

**Configure client scopes and attribute mappers**

1. Navigate to the **Client Scopes** tab for the client.
2. Select the dedicated scope and mappers for the client (`https://<workspace-url>/_saml/metadata/keycloak-dedicated`).
3. Go to the **Mappers** tab to create mappers for the required data that your Rocket.Chat workspace expects. Typically, **email** or **username** mappers aren't needed, but **cn** (common name) may be required.
4. Click **Configure a new mapper** and select **User Property** as the Mapper Type.
5. Set the **SAML Attribute NameFormat** to `basic`.
6. For the first name:
  1. Set **Name** and **Property** to `firstName`.
  2. Set **SAML Attribute Name** to `cn`.
7. Click **Save**.

## Authenticating Keycloak users to Rocket.Chat

After completing the configuration, users can click the SAML button on the workspace login page. This action will redirect them to Keycloak’s authentication page, where they can log in with their credentials. Upon successful login, users are redirected back to their account on the workspace. You can monitor active sessions of your Keycloak users on Rocket.Chat by checking the **Sessions** tab in Keycloak.

### Creating users in Keycloak

If you don’t have users set up in Keycloak yet, follow these basic steps to create a new user:

1. Navigate to the **Users** section in Keycloak and click **Create User**.
2. Fill in the required fields, then click **Create**.
3. Go to the user's **Credentials** tab and set a password.

You can also configure the user interface, behavior, and mapping settings according to your requirements.

## Troubleshooting

You may run into some problems for various reasons:

- Q: I keep getting the `Unable to validate response url: Error: Status is: urn:oasis:names:tc:SAML:2.0:status:Responder` error.
  - A: Make sure that the respective Keycloak user has an e-mail address. This may not be the case. For example, for the Keycloak admin.