Custom OAuth Setup

You can allow users to sign in to your Rocket.Chat workspace using their Auth0 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
Admin access to your 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

Log in to your Auth0 dashboard.
Go to Applications → Applications → Create Application.
Enter the app details:
- Name: A name for your application, for example, RocketChat
- Application type: Select Regular Web Applications
Click Create.
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.

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.

Important
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 workspace:

Go to Manage → Workspace → Settings → OAuth.
Click Add custom OAuth.
Enter a unique name for the new OAuth integration, for example, testcustom. This name is used to build the Callback URL.
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. Changing the colors may result in non-compliance with WCAG (Web Content Accessibility Guidelines) 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.
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 channel names. For example: `{ "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.