--- title: "Custom OAuth Setup" slug: "custom-oauth-setup" updated: 2026-10-26T17:12:35Z published: 2026-10-26T17:12:35Z canonical: "docs.rocket.chat/custom-oauth-setup" --- > ## 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. # Custom OAuth Setup ![](https://cdn.us.document360.io/6ae79a05-7252-45d0-96e8-8f375e07b1b2/Images/Documentation/Premium(13).svg) > [!WARNING] > From Rocket.Chat 9.0.0, Custom OAuth 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. You can allow users to sign in to your Rocket.Chat workspace using their [Auth0](https://auth0.com/) accounts. Auth0 is an identity platform that provides authentication, single sign-on, and user management for web and mobile applications. This guide shows how to set up a custom OAuth integration between Auth0 and Rocket.Chat. ## Prerequisites Before setting up Auth0 custom OAuth, you need: - An [Auth0 account](https://auth0.com/signup) - Admin access to your [Rocket.Chat](http://Rocket.Chat) workspace ## Set up Auth0 To use Auth0 as a sign-in method, you first need to create an Auth0 application and gather its credentials. ### Create an Auth0 application 1. Log in to your [Auth0 dashboard](https://manage.auth0.com/). 2. Go to **Applications → Applications → Create Application**. 3. Enter the app details: - **Name**: A name for your application, for example, `RocketChat` - **Application type**: Select **Regular Web Applications** 4. Click **Create**. 5. After Auth0 creates the app, open its **Settings** tab and copy the **Domain**, **Client ID**, and **Client Secret**. You will need these values to configure the integration in Rocket.Chat. ![](https://cdn.us.document360.io/6ae79a05-7252-45d0-96e8-8f375e07b1b2/Images/Documentation/image(326).png) ### Configure Application URIs In your Auth0 application **Settings**, scroll to **Application URIs** and fill in the following fields. Replace `<your-rocketchat-domain>` with your Rocket.Chat workspace URL and `<oauth-name>` with the unique name you will give your custom OAuth integration in Rocket.Chat. | Field | Value | | --- | --- | | **Application Login URI** | `https://<your-rocketchat-domain>/login` | | **Allowed Callback URLs** | `https://<your-rocketchat-domain>/_oauth/<oauth-name>` | | **Allowed Logout URLs** | `https://<your-rocketchat-domain>/` | | **Allowed Web Origins** | `https://<your-rocketchat-domain>/` | For example, if your workspace URL is `https://test.rocket.chat` and your OAuth name is `testcustom`, the callback URL is `https://test.rocket.chat/_oauth/testcustom`. Click **Save Changes** at the bottom of the page. > [!WARNING] > - **Copy the Callback URL from Rocket.Chat after you create the custom OAuth integration, then paste it into your Auth0 app settings as the Allowed Callback URL.** > - **If the callback URLs do not match exactly, sign-in will fail.** --- ## Create custom OAuth To create a custom authentication method in your [Rocket.Chat](http://Rocket.Chat) workspace: 1. Go to **Manage → Workspace → Settings → OAuth**. 2. Click **Add custom OAuth**. 3. Enter a unique name for the new OAuth integration, for example, `testcustom`. This name is used to build the Callback URL. 4. After creating the new integration, Rocket.Chat displays the **Callback URL** at the top of the configuration panel. For example, `https://<your-rocketchat-domain>/_oauth/testcustom`. Copy this value and paste it into your Auth0 app as the **Allowed Callback URL**. ### Configure custom OAuth In your workspace, enable the custom OAuth and set the following fields: | Field | Description | | --- | --- | | **Enable** | Toggle on to activate this OAuth integration. | | **URL** | Enter your Auth0 domain as a full URL, in the format `https://<your-auth0-domain>`. For example, in the case of `https://mycompany.us.auth0.com`, do not include a trailing slash or any path. Rocket.Chat appends the Token Path, Identity Path, and Authorize Path to this base URL. | | **Token Path** | Enter `/oauth/token`. This is Auth0's token endpoint. | | **Token Sent Via** | Defines how the client credentials are sent to the token endpoint. The options are: - **Payload**: Sends credentials in the request body. - **Header**: Sends credentials in the HTTP Authorization header. For Auth0, leave the default value **Payload**. | | **Identity Token Sent Via** | Defines how the access token is sent when Rocket.Chat requests the user identity. The options are: - **Same as "Token Sent Via"**: Uses the same method selected in the **Token Sent Via** field. - **Header**: Sends the token in the HTTP Authorization header. - **Payload**: Sends the token in the request body. For Auth0, leave the default value **Same as "Token Sent Via"**. | | **Identity Path** | The user info endpoint path. The default value `/me` works with Auth0. Leave the default. If the default does not return user profile data in your tenant, change it to `/userinfo`, the standard Auth0 OIDC endpoint. | | **Authorize Path** | The authorization endpoint path. The default value `/oauth/authorize` is correct for Auth0. Leave the default. | | **Scope** | The OAuth scopes requested from Auth0. The default value `openid` is the minimum required. To request additional user profile claims and group information, change it to `openid email profile`. To sync roles and groups, you may also need to add custom scopes configured in your Auth0 tenant. | | **Param Name for access token** | The parameter name used to send the access token. The default value `access_token` is correct for Auth0. Leave the default. | | **Id** | Enter the **Client ID** value from your Auth0 application settings. | | **Secret** | Enter the **Client Secret** value from your Auth0 application settings. | | **Login Style** | Defines how the Auth0 login screen is displayed. The options are: - **Redirect**: Redirects the user to Auth0 and back. - **Popup**: Opens the Auth0 login in a popup window. - **Default**: Uses the Rocket.Chat default behavior. For Auth0, leave the default value **Popup**. | | **Button Text** | The text displayed on the login button. The default value is `Custom OAuth`. Change it to something more descriptive, for example, `Login with Auth0`. | | **Button Text Color** | The color of the login button text in hex format. The default value is `#FFFFFF`. Change it if you want the text to match your branding. > [!WARNING] > Changing the colors may result in non-compliance with [WCAG (Web Content Accessibility Guidelines)](https://www.w3.org/TR/WCAG21/) requirements. Ensure that the new colors meet the recommended contrast and readability standards to maintain accessibility for all users. | | **Button Color** | The background color of the login button in hex format. The default value is `#1d74f5`. Change it if you want the button to match your branding. | | **Key Field** | Select the field that uniquely identifies users between Auth0 and Rocket.Chat. The options are: - **Username**: Matches users by their preferred username. - **Email**: Matches users by their email address. For Auth0, leave the default value **Username**. | | **Username field** | The claim key from the Auth0 user info response that contains the username. The default value `preferred_username` is correct for Auth0. Leave the default. | | **Email field** | The claim key that contains the user email. The default value `email` is correct for Auth0. Leave the default. | | **Name field** | The claim key that contains the user's display name. The default value `name` is correct for Auth0. Leave the default. | | **Avatar field** | Enter the claim key that contains the user's avatar URL. Auth0 typically returns a `picture` claim. Leave blank if not used. | | **Roles/Groups field name** | The claim key in the user info response that contains the user's roles. The default value `roles` works if your Auth0 tenant is configured to return a `roles` claim. The exact claim name depends on how your Auth0 tenant is configured. See [Auth0 documentation on custom claims](https://auth0.com/docs/secure/tokens/json-web-tokens/create-custom-claims). | | **Roles/Groups field for channel mapping** | Enter the claim key in the user info response that contains the groups used for channel mapping. For example, `groups`. | | **User Data Group Map** | Enter the default group name to assign to users if no group claim is returned. For example, `rocket.cat`. | | **Map Roles/Groups to channels** | Toggle on to automatically add users to Rocket.Chat channels based on the OAuth Group Channel Map. | | **Merge Roles from SSO** | Toggle on to merge roles from Auth0 with the user's existing Rocket.Chat roles. When off, Auth0 roles replace existing roles on each login. | | **Roles to Sync** | Enter a comma-separated list of OAuth roles to sync on user login and creation. Leave blank to sync all roles. | | **Merge users** | Toggle on to merge OAuth users with existing Rocket.Chat users when the Key Field matches. | | **Merge users from distinct services** | Toggle on to allow merging users from this OAuth service with existing users from other OAuth services, when the Key Field matches. | | **Show Button on Login Page** | Toggle on to display the Auth0 login button on the Rocket.Chat login page. | | **OAuth Group Channel Map** | Enter a JSON object that maps Auth0 group names to [Rocket.Chat](http://Rocket.Chat) channel names. For example: ```bash { "rocket-admin": "admin", "tech-support": "support" } ``` Users in the `rocket-admin` group are added to the `admin` channel, and users in the `tech-support` group are added to the `support` channel. | Click **Save changes**. After you save, click **Refresh OAuth Services**. The login button with the text you configured under **Button Text**, for example, `Login with Auth0`, appears on the workspace sign-in page. Users can then sign in with their Auth0 accounts. ![](https://cdn.us.document360.io/6ae79a05-7252-45d0-96e8-8f375e07b1b2/Images/Documentation/image(328).png)