SAML Configuration

From version 9.0.0 on, this authentication method requires a Premium plan. Workspaces without a license covering it will not be able to authenticate users through it after the upgrade.

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 Manage → 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: Turn the SAML connection on or off.

• 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 terms, this is the Single Logout Service (SLS) endpoint using the HTTP-Redirect binding

  (urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect).

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

  Example:

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

• Enable Debug: Logs detailed information during SAML requests. Useful for troubleshooting.

Starting with Rocket.Chat 8.4.0, the IDP SLO Redirect URL is validated on every Single Logout request.

Requirements:

• This field is mandatory. If left empty, logout requests will fail.

• The value must match your IdP's SLO endpoint exactly. Even small differences will cause failures.

• If you are unsure of your IdP's SLO endpoint, check its SAML metadata or contact your IdP administrator.

Example:

If your IdP uses  https://idp.example.com/saml/slo , then you must configure https://idp.example.com/saml/slo

Invalid variations include:

• Using http:// instead of https://

• A different path

• A different subdomain

Certificate

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

Import IdP metadata

This feature is available since Rocket.Chat 8.8.0.

Instead of copying values from your identity provider manually, you can import them from your IdP's metadata URL. Rocket.Chat fetches and parses the metadata document, then prefills the extracted values into the SAML settings form for you to review before saving.

To import IdP metadata:

1. On the SAML settings page, click Import IdP metadata in the top-right corner.

2. Enter your identity provider's Metadata URL and click Fetch metadata.

3. Review the extracted values. Every field is editable, so you can adjust any value before applying. If a value is not present in the metadata, the field shows Not found in metadata and is left for you to fill in manually.

4. Click Apply. The values are applied to the SAML settings form, review them, then click Save changes.

The following values are extracted from the IdP metadata:

Imported values are not saved automatically, nothing changes in your workspace until you click Save changes. Service-provider settings, such as Custom Issuer, your own certificates and keys, and attribute mappings, are never modified by the import.

If the URL is unreachable or the document is not valid SAML IdP metadata, an error is displayed in the dialog and no settings are changed. Correct the URL and try fetching again.

If your identity provider is hosted on an internal network or private IP address, the metadata fetch is blocked by SSRF protection. Add the IdP host to the SSRF allowlist under Manage → Workspace → Settings → General → SSRF protection before importing.

Premium Settings

The following premium SAML settings are exclusively 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 let 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.

SAML sign-in from the mobile and desktop apps

Starting with Rocket.Chat 8.8.0, users signing in with SAML from the Rocket.Chat mobile and desktop apps complete authentication in their system browser instead of an embedded view within the app.

When a user taps the SAML login button in the app:

1. The system browser opens with your identity provider's sign-in page. If the user already has an active session with the IdP in that browser, it is reused.

2. After authentication, the browser hands the session back to the app automatically, and the user is signed in.

Because authentication happens in a full browser, phishing-resistant MFA methods such as passkeys and security keys work during SAML sign-in from the apps.

No additional SAML configuration is required, but this flow requires the Use Modern OAuth Flow setting to be enabled under Manage → Workspace → Settings → OAuth, and a mobile or desktop app version that supports it.

If the user closes the browser before completing sign-in, the app remains on the login screen and they can try again.

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.