--- title: "Rocket Chat SAML Setup with Microsoft Entra ID" slug: "microsoft-entra-id-saml-setup-example" description: "Follow Microsoft Entra ID setup for SAML in Rocket Chat. Ensure secure login, compliance, and collaboration resilience." updated: 2026-10-26T16:57:25Z published: 2026-10-26T16:57:25Z canonical: "docs.rocket.chat/microsoft-entra-id-saml-setup-example" --- > ## 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. # Microsoft Entra ID - SAML Setup Example ![](https://cdn.us.document360.io/6ae79a05-7252-45d0-96e8-8f375e07b1b2/Images/Documentation/Premium(10).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. Rocket.Chat’s SAML configuration can be integrated with [Microsoft Azure Entra ID](https://docs.azure.cn/en-us/entra/fundamentals/whatis) SAML identity provider. If your organization uses Microsoft Entra ID for employee identity verification, management, and access, you can map your Entra ID users to your Rocket.Chat workspace. This helps you streamline user identity management. This guide walks you through an example to integrate Entra ID with Rocket.Chat. ## Prerequisites - A Microsoft Azure Entra ID tenant containing users and groups according to your needs. Refer to the [Microsoft Entra ID documentation](https://docs.azure.cn/en-us/entra/fundamentals/create-new-tenant) for details. - A Rocket.Chat workspace with admin access. ## Add an enterprise application Log in to your Azure portal account and access your Entra ID tenant. Follow these steps to create an enterprise application: 1. Go to **Manage** → **Enterprise applications**. On the **All applications** page, click **New application**. 2. On the **Browse Microsoft Entra Gallery** page, search for **Microsoft Entra SAML Toolkit**. 3. In the side pane that opens, enter a new name for your enterprise application, for example, `Rocket.Chat SAML`. 4. Click **Create**. Your enterprise application will be created. For further details, you can refer to the [Microsoft enterprise application quickstart guide](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal). > [!NOTE] > **Tip**: Add your users or groups to this application from **Manage** → **Users and groups**. Doing this provides the SAML application with access to the users in the groups, so these users can sign in to Rocket.Chat once the configuration is complete. ## Connect the enterprise application to the workspace Once the application is created, we will connect it to the Rocket.Chat workspace. Follow these steps: 1. In the newly created enterprise application, go to **Manage** → **Single sign-on**. On this page, you can find the configuration properties. We will connect this application to the Rocket.Chat workspace. 2. In your workspace, 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**. 3. Enter a name for the connection in the **Custom Provider** field, for example, `entra`. 4. In the **Custom Entry Point** field, copy and paste the value from the enterprise application’s **Login URL**. For example, `https://login.microsoftonline.com/6024a0e7-xxxx-xxxx-xxxx-335414008b76/saml2` 5. In the **IDP SLO Redirect URL** field, copy and paste the value from the enterprise application’s **Logout URL**. For example, `https://login.microsoftonline.com/6024a0e7-xxxx-xxxx-xxxx-335414008b76/saml2` The following screenshot shows the enterprise application on the left and the workspace settings on the right: ![](https://cdn.us.document360.io/6ae79a05-7252-45d0-96e8-8f375e07b1b2/Images/Documentation/image-1746598961262.png) 1. The screenshot also shows an example value for the **Custom Issuer** field in the workspace. The format of the value is `https://<your-rocket-chat-domain>/_saml/metadata/<custom-provider-name>`. Replace the domain with your Rocket.Chat workspace domain name and the **Custom Provider** value at the end. For example, `https://demo.rocket.chat/_saml/metadata/entra` 2. You can use the **Enable Debug** option to get debugging information in the [workspace logs](/v1/docs/configure-workspace-logs#view-workspace-logs). ## Configure SAML single sign-on in the enterprise application Now we will configure SAML single sign-on in the Entra ID enterprise application. Follow these steps: 1. From your Rocket.Chat workspace’s SAML settings, copy the **Custom Issuer** URL, and paste it in a new browser tab. The XML metadata file is displayed. We will use values from here to configure the Entra ID application. For example, it looks something like this based on your configuration: ```xml          urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress       ``` 1. In your Entra ID enterprise application, click **Edit** next to **Basic SAML Configuration**. 2. In the **Identifier (Entity ID)** field, copy and paste the **entityID** URL from the metadata file. For example, `https://demo.dev.rocket.chat/_saml/metadata/entra` 3. In the **Reply URL (Assertion Consumer Service URL)** field, copy and paste the **Location** URL from the **AssertionConsumerService** property in the metadata file. For example, `https://demo.dev.rocket.chat/_saml/validate/entra` 4. In the **Sign on URL** field, enter your workspace URL. For example, `https://demo.dev.rocket.chat/` 5. In the **Logout Url** field, copy and paste the **Location URL** from the **SingleLogoutService** property in the metadata file. For example, `https://demo.dev.rocket.chat/_saml/logout/entra/` 6. Click **Save**. The following screenshot shows an example of the SAML configuration values: ![](https://cdn.us.document360.io/6ae79a05-7252-45d0-96e8-8f375e07b1b2/Images/Documentation/image-1746695369760.png) For further details, you can refer to the [Microsoft SAML single sign-on guide](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal-setup-sso) for enterprise applications. ## Modify attributes and claims Rocket.Chat needs to receive SAML tokens (or claims) to sign in users from Entra ID. In this step, we will modify the attributes and claims that can be received by Rocket.Chat. Keep in mind that the following steps provide an example for the setup. Your organization’s configurations may differ, and you can modify the values according to your needs. 1. Click **Edit** next to **Attributes & Claims**. 2. Under **Additional Claims**, click the claim name with **Value** as **user.mail**. 1. For this claim, remove the **Namespace** URL value. 2. Leave the **Name** value as **emailaddress**. We will use this value later to map it to Rocket.Chat. 3. For the **Source attribute** field, select **user.userprincipalname** from the drop-down menu. This means that the value from users’ **User principal name** property will be used as their email addresses in Rocket.Chat. You can change this source value according to your configurations. 4. Click **Save**. 3. We need a value for users’ display names. For this, we will create a new claim. On the **Attributes & Claims** page, click **Add new claim**. 1. Enter the **Name** as **displayname**. 2. For the **Source attribute** field, select **user.displayname** from the drop-down menu. This means that the value from users’ **Display name** property will be used as their display names in Rocket.Chat. You can change this source value according to your configurations. 3. Click **Save**. Your **Attributes & Claims** section can look something like this: ![](https://cdn.us.document360.io/6ae79a05-7252-45d0-96e8-8f375e07b1b2/Images/Documentation/image(206).png) For further details, you can refer to Microsoft’s guide on [SAML token claims customization](https://learn.microsoft.com/en-us/entra/identity-platform/saml-claims-customization). ## Map claims to the workspace In the previous step, we created and modified the necessary claims in the Entra ID SAML application. Now, follow these steps to map the claims to the Rocket.Chat workspace: 1. In the Rocket.Chat workspace, go to the SAML settings page. In the **General** tab, click to expand the **Mapping** section. 2. We will enter a JSON object as the value for **User Data Field Map** as follows: ```json {  "email":"emailaddress",  "name": "displayname" // the values are the claim names that we defined in the Entra SAML application in the previous step  "username":{               "fieldName": "emailaddress",               "regex": "(.*)@.+$",               "template": "__regex__"}, // this object splits the `emailaddress` claim; then it takes the part before the @ symbol as the username. For example, if the email address in Entra ID is `jane.doe@example.com`, then the username in Rocket.Chat will be `jane.doe` } ``` According to your configurations, the claim names may differ. Check the **Attributes & Claims** section in your Entra ID SAML application for the correct values. The available fields in Rocket.Chat are `name`, `email`, and `username`, everything else will be discarded. ## SAML verification certificates If you want to enable signed authentication requests for the SAML application, follow these steps: 1. Generate your own private key and TLS certificate. Skip this step if you have your own public certificate and private key. 1. In the command-line tool of your choice, enter the command to generate a private key: `openssl genrsa -out sp-private.key 2048` 2. Optionally, you can generate a certificate signing request using the command: `openssl req -sha256 -new -key sp-private.key -out sp.csr`. You are prompted to enter details such as your country, state, organization, and email address. Enter the details according to your needs. 3. Generate a self-signed certificate valid for 10 years using the command: `openssl x509 -req -sha256 -days 3650 -in sp.csr -signkey sp-private.key -out sp-cert.crt` 4. Convert the certificate file to a `.cer` file as Entra ID only accepts the `.cer` file format. Use the command: `openssl x509 -outform DER -in sp-cert.crt -out sp-cert.cer` 2. Now that our certificates are ready, we will enable secure SAML authentication. In the Entra ID SAML application, go to the **SAML Certificates** section on the **SAML-based Sign-on** page. 3. Click **Edit** next to **Verification certificates (optional)**. 4. Enable the **Require verification certificates** and **Allow requests signed with RSA-SHA1** checkboxes. Enabling the second checkbox is required because Rocket.Chat currently signs all SAML requests using the `RSA-SHA1` algorithm. 5. Click **Upload certificate**. Upload your `.cer` public certificate file. In this example, it will be the `sp-cert.cer` file. 6. Click **Save**. The following screenshot shows an example of the application: ![](https://cdn.us.document360.io/6ae79a05-7252-45d0-96e8-8f375e07b1b2/Images/Documentation/image-1746613659404.png) For further information, you can refer to the Microsoft guide on [enforcing signed SAML authentication requests](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/howto-enforce-signed-saml-authentication). ### Provide certificates in the workspace Next, we will need to copy and paste the corresponding certificates to the Rocket.Chat workspace. Follow these steps: 1. In your Rocket.Chat workspace, go to the SAML settings page. 2. On the **Connection** tab, click to expand the **Certificate** section. 3. Copy the public certificate file content (in this example, `sp-cert.crt` file) and paste it in the **Public Cert Contents** field. 4. Copy the private key file content (in this example, `sp-private.key` file) and paste it in the **Private Key Contents** field. 5. Select the **Signature Validation Type** field as **Validate Either Signature**. 6. Click **Save changes**. The following screenshot shows an example of the **Certificate** section: ![](https://cdn.us.document360.io/6ae79a05-7252-45d0-96e8-8f375e07b1b2/Images/Documentation/image(209).png) ## Set workspace’s user interface and behavior Rocket.Chat provides settings to define the user login and logout behavior. In the workspace, go to the SAML settings and select the **General** tab. - In the **User Interface** section, you can change the login **Button Text** that is displayed on the workspace’s login page. For example, `Login with Entra ID SAML`. Additionally, you can change the colors according to your needs. - In the **Behavior** section, you can define how users’ details are managed and the logout behavior. See the [SAML Configuration - General](/v1/docs/saml-configuration#general) guide for details. Great! Our Entra ID SAML configuration with Rocket.Chat is now complete, and you can test the connection. ## Test the Entra ID SAML setup If you want to test the configuration, you can use a dummy user. Create a test user profile in your Entra ID tenant and set the properties according to your needs. Then access your Rocket.Chat workspace URL in any browser. Click the SAML login button below the username and password fields. You will be redirected to Microsoft’s authentication screen. You should be able to log in with the test user's credentials. Alternatively, you can sign in to [office.com](https://www.office.com/) with the test user’s credentials. After that, access the Rocket.Chat workspace URL in a new tab. You will be logged in automatically. Based on your organization’s requirements, users may need to verify their identity while logging in using an authenticator app, such as Microsoft Authenticator. ## Troubleshooting - The configured SAML connection blocks unassigned users from signing in to Rocket.Chat. They may see an error as shown in the following screenshot: ![](https://cdn.us.document360.io/6ae79a05-7252-45d0-96e8-8f375e07b1b2/Images/Documentation/Screenshot 2025-05-08 112350(1).png) Ensure that the users are assigned to the Entra ID SAML enterprise application that you created. To do this, go to the SAML application page and access **Manage** → **Users and groups**. On this page, add the groups or users of your organization who will access the Rocket.Chat workspace. - If users are unable to sign in to Rocket.Chat, check your **Mapping** section in the workspace’s SAML settings and the **Attributes & Claims** section in the Entra ID application. Make sure that the values are mapped correctly. - For further information, you can also check the [**Reports**](/v1/docs/configure-workspace-logs#view-workspace-logs) tab to view the workspace logs.