Keycloak

Keycloak is an open-source identity and access management software. It supports user federation, OAuth, SAML, and OpenID Connect protocols. Along with role-based authorization, you can also connect to existing LDAP user directories. Rocket.Chat supports Keycloak configuration for you to securely manage your users and resources.

This guide walks you through a basic Keycloak OpenID Connect setup in Rocket.Chat to log in with Keycloak credentials.

Configure Keycloak OpenID Connect

To create a client in Keycloak, follow these steps:

1. Enter a Client ID, for example, rocket-chat-client.

2. Select the Client Protocol as openid-connect.

3. Select the Access Type as confidential. Setting the client as confidential means that a client secret is required to initial the login.

4. Enable the Standard Flow Enabled field.

5. Enter the Valid Redirect URIs, for example, https://{demo.rocket.cat}/*

Save the client. A new credentials tab will be created for the client. This credentials tab will provide the client secret to be used when configuring Keycloak in your Rocket.Chat workspace.

Configure Keycloak in Rocket.Chat

1. Login to Rocket.Chat with an administrator account and navigate to the OAuth page in the Settings tab.

2. Click the Add custom OAuth button and enter the following details:

Field	Description	Example
URL	The URL of the OpenID Connect issuer in the Keycloak realm.	https://keycloak.support.rocket.cat/realms/{realm-name}/protocol
Token Path	The token endpoint is used to obtain access tokens. Enter the path from the token endpoint.	/openid-connect/token
Token sent via	Select whether the token is sent via Header or Payload.	Header
Identity Token Sent Via	Select whether the identity token is sent via Header, Payload, or the same method as the Token sent via field.	Token sent via
Identity Path	The user information endpoint is used to retrieve user data. Enter the path from the user endpoint.	/openid-connect/userinfo
Authorize Path	Enter the path from the authorization endpoint.	/openid-connect/auth
Scope	The scope defines the user access level and permissions that you have configured in Keycloak.	openid
Param Name for access token	The name of the access token.	access_token
Id	The client ID that you created in Keycloak.	rocket-chat-client
Secret	Enter the client secret from your Keycloak client's Credentials tab.	QTrbVadjfjhurUzsJHRbteQPHHm8Od6w
Button Text	Enter the text to be displayed on the login screen.	Login with Keycloak

To access the URL paths provided in the configurations, go to Realm Settings > General and click the endpoints link. While configuring the settings, replace realm_name with the appropriate realm name. The default realm provided by Keycloak is master.

3. You can leave the rest of the configurations as default. Click Save changes.

4. Enable the new Keycloak provider. Click Refresh OAuth Services.

5. If you are in a test environment with no SMTP server set, disable two-factor authentication in Administration > Settings > General.

A Login with Keycloak button is displayed on your workspace's login page. Users can now log in with their Keycloak credentials!

For more information on Keycloak server setup and roles, see Server Administration Guide.

Advanced configuration

In this section, we talk about some advanced configuration options to map and sync your user data.

Map Keycloak groups to Rocket.Chat rooms

Let's say that you want to add users from a Keycloak group to Rocket.Chat rooms. For this, keep the following points in mind:

• The Map Roles/Groups to channels field must be enabled.

• Provide the Keycloak groups in the Roles/Groups field for channel mapping in the OAuth settings.

• In the OAuth Group Channel Map field, enter the group to rooms mapping data in the JSON format. From this mapping, users that belong to the specific Keycloak groups are inserted into all the associated Rocket.Chat rooms. For example, the mapping can look like this:

{
    "keycloak-group": ["rocket-chat-room-name-1", "rocket-chat-room-name-2"]
}
// users in the "keycloak-group" are added to the specified rooms

If any of the rooms don't exist, Rocket.Chat creates the rooms as public rooms when a user from the Keycloak group logs in.

Note that user groups would not be returned from the Keycloak OAuth response by default. So let's look at an example of how to get the groups from Keycloak.

1. In Keycloak, create a group. For example, Managers. Let some users be added to this group. We will map this group to Rocket.Chat rooms.

2. Add a client scope for the group for Rocket.Chat to retrieve, and enter the required information. For example, create a client scope called groups.

3. Now go to Mappers > Add Mapper > By Configuration > Group Membership. Fill in the details of the group membership called groups. The following screenshot shows an example:

4. After saving this, go to Clients and select the client you are using for the Rocket.Chat workspace.

5. Go to the Client scopes tab and click Add client scope. Select the client scope for the group that you just created; in this example, groups.

Our Keycloak group is ready to be mapped to Rocket.Chat. In your workspace OAuth settings, enter the following details:

• Roles/Groups field for channel mapping: groups

• Enable the Map Roles/Groups to channels setting.

• Enter the following in the OAuth Group Channel Map field:

{
    "Managers": "managers-channel"
}

The following screenshot shows the example:

Save your changes. In this way, all users from the Managers group are mapped to the managers-channel room.

Merge and sync roles from Keycloak to Rocket.Chat

Keep the following points in mind:

• You must set the Roles/Groups field name field as groups.

• The Merge Roles from SSO option merges and mirrors the Keycloak user roles in the Rocket.Chat workspace. If you add or remove roles in Keycloak, this is replicated in Rocket.Chat.

• In the Roles to Sync field, you can specify a list of role names to be mirrored on every new user login and sync.

Make sure that you create roles in Rocket.Chat with the same names as in Keycloak for this to work successfully.