Keycloak

Keycloak is an open-source identity and access management solution supporting user federation, OAuth, SAML, and OpenID Connect protocols. Rocket.Chat integrates with Keycloak using SAML, enabling secure management of users and resources. This guide explains how to configure Keycloak with Rocket.Chat using SAML for users to log in with their Keycloak credentials.

Prerequisites

A Rocket.Chat workspace (e.g., https://test-rocket.chat).
A Keycloak server (e.g., https://keycloak.test.com).
A Keycloak realm 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 section of Rocket.Chat settings:

Go to Administration > Workspace > Settings > SAML
Enable the SAML connection in Rocket.Chat.
Set the Custom Provider to keycloak.
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.
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 under Rocket.Chat SAML settings:

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.
Generate a certificate pair for Rocket.Chat:
- Run the following OpenSSL command to generate a public certificate and a private key:
```
openssl req -newkey rsa:3072 -new -x509 -days 3652 -nodes -out saml.crt -keyout saml.pem
```
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.
Set the Signature Validation Type to Validate Either Signature.
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

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.
Save the raw XML file to your device.

Import the client in keycloak

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

Configure the client settings

Ensure the Client ID matches the metadata URL.
Verify the Valid Redirect URIs field is set to https://<workspace-url>/_saml/validate/keycloak.
Set the Name ID Format to email.
Set SAML Signature Key to KEY_ID.
Click Save.

Verify the public key (certificate)

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.
The -----BEGIN/END CERTIFICATE----- header/footer is not displayed in Keycloak, but the rest of the certificate should match.
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

Navigate to the Client Scopes tab for the client.
Select the dedicated scope and mappers for the client (https://<workspace-url>/_saml/metadata/keycloak-dedicated).
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.
Click Configure a new mapper and select User Property as the Mapper Type.
Set the SAML Attribute NameFormat to basic.
For the first name:
1. Set Name and Property to firstName.
2. Set SAML Attribute Name to cn.
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:

Navigate to the Users section in Keycloak and click Create User.
Fill in the required fields, then click Create.
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.