SAML Configuration

This section walks you through the available SAML configuration settings in Rocket.Chat. These settings allow you to tailor the user sign-in process, map user data, and access additional premium options.

In your Rocket.Chat workspace, go to Administration > Workspace > Settings > SAML. On the SAML page, you’ll find the configuration tabs where you can input the details from your identity provider (IdP). Make sure you have an IdP set up (for example, ADFS or Keycloak) and the required credentials.

You can refer to Active Directory Federation Services and Keycloak for provider-specific configuration guides and sample values.

Connection settings

These settings define the base connection to your SAML identity provider:

• Enable: Toggle to activate or deactivate the SAML connection.

• Custom Provider: The name of your SAML provider (for example, entra).

• Custom Entry Point: The login URL provided by your IdP. This is where authentication requests are sent.

• IDP SLO Redirect URL: The logout URL provided by your IdP. In SAML terminology, this is the location (URL) of the SingleLogoutService, using the redirect binding (urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect).

• Custom Issuer: The unique URI that identifies your Rocket.Chat service. By convention, this is also the URL of your unedited metadata. For example:

  https://my-rocketchat-domain.tld/_saml/metadata/my-app

• Enable Debug: Enable to log debug details during SAML requests and responses—helpful for troubleshooting issues.

Certificate

Configure certificates used for signing and validating SAML requests and responses. The available settings are:

Premium Settings

The following premium SAML settings are only available to workspaces on Rocket.Chat’s premium plans. They provide advanced options for role assignment, authorization policies, and attribute mapping.

Advanced

The Advanced settings let you configure SAML request and response templates, identifier formats, and context policies. The available settings are:

Roles

Role settings let you synchronize user roles between your SAML identity provider and Rocket.Chat. The available settings are:

• Sync User Roles: Enable to sync user roles during login. This overwrites any roles previously assigned locally in Rocket.Chat.

• Role Attribute Name: If this attribute is included in the SAML response, its values will be applied as role names for new users.

Mapping

Mapping settings lets you configure how user custom fields are populated from records in SAML responses. The available setting is:

• User Data Custom Field Map: Defines how user custom fields in Rocket.Chat should be populated from attributes in the SAML response. Once a matching attribute is found in the SAML record, its value will be mapped to the corresponding Rocket.Chat custom field.

  Example:

  {
    "custom1": "custom1",
    "custom2": "custom2",
    "custom3": "custom3"
  }

General settings

The General settings in SAML configuration allow you to customize how users interact with the login interface and how their data is handled during authentication. These settings control three main areas.

User Interface

The User Interface settings let you customize the appearance of the SAML login button, including its text and colors, to align with your organization’s branding while maintaining accessibility. The available settings are:

• Button Text: The text displayed on the SAML login button.

• Button Text Color: Sets the color of the button text. Ensure chosen color meets WCAG (Web Content Accessibility Guidelines) contrast and readability standards to maintain accessibility.

• Button Color: Sets the background color of the SAML login button. Changing this may affect WCAG compliance, verify that the new color maintains proper contrast and accessibility for all users.

Accessibility note

Any changes to button text color or button background color may result in non-compliance with WCAG accessibility requirements. Always test your color choices for contrast and readability.

Behaviour

The Behavior settings in SAML control how user accounts are managed during sign-in, covering usernames, attributes, sessions, roles, subscriptions, and IdP timing to keep Rocket.Chat consistent with your identity provider. The available settings are:

Mapping

Mapping defines how user account fields from the SAML response (like email, username, and name) are assigned to Rocket.Chat user fields. This ensures correct synchronization between the Identity Provider (IdP) and Rocket.Chat. The available setting is:

• User Data Field Map: Defines how user attributes from the SAML response are mapped to Rocket.Chat user fields. Configure attributes such as username, email, and name using JSON mapping.

Example Configuration

Here’s an example of how fields can be mapped from SAML attributes:

{
  "email": "mail",
  "username": {
    "fieldName": "mail",
    "regex": "(.*)@.+$",
    "template": "user-__regex__"
  },
  "name": {
   "fieldNames": [
      "firstName",
      "lastName"
    ],
    "template": "__firstName__ __lastName__"
  },
  "__identifier__": "uid"
}

• Available fields in Rocket.Chat: name, email, username. Any other attributes will be discarded.

  Example:

  {"name": "cn", "email": "mail"}

  This maps the user’s human-readable name from the cn attribute and their email from the mail attribute.

This concludes the configuration options available for setting up SAML integration in Rocket.Chat. With these settings, administrators can fine-tune authentication, user roles, data mapping, and interface behavior to ensure seamless synchronization with their Identity Provider.

In the upcoming sections, we will explore common SAML identity providers and walk through practical examples of how to integrate them with Rocket.Chat.