MS Office 365 Custom OAuth Setup

In addition to the OAuth methods that Rocket.Chat provides for user authentication, you can also choose to set up a custom OAuth method.

This guide shows how to set up a custom OAuth integration between Microsoft accounts and Rocket.Chat. This is achieved with Microsoft Entra ID (formerly called Azure Active Directory), which is an identity service by Microsoft that provides single sign-on and other authentication methods. You can also define conditional access policies and role-based permissions.

Prerequisites

  • An account on the Azure portal.

  • An Azure Active Directory web application (Microsoft identity platform).

  • An application ID and client secret.

    • If you don't have an app, log in to the Azure Portal and go to the Microsoft Entra ID section.

    • Create a new App Registration.

    • Fill in the details. You will get the redirect URI from your Rocket.Chat workspace when you Create Custom O365 OAuth.

    • After registering your new app, note the Application (client) ID and the Directory (tenant) ID. You will need these values to configure the integration in Rocket.Chat.

    • On your new app's page, go to the Certificates and Secret tab to create a New client secret. Make sure you note the secret value.

Create custom OAuth

To create a custom authentication method in your Rocket.Chat workspace, follow these steps:

  • Go to Administration > Workspace > Settings > OAuth.

  • Click on Custom OAuth and enter a name for the new OAuth integration.

  • After creating the new integration, you are given the Callback URL. For example, https://<your-domain>/_oauth/ms365. Enter this as the redirect URI when you are creating your Azure app.

  • You will also need to fill in other configuration fields.

Configure custom OAuth

In your workspace, enable the custom OAuth and set the following fields as per your requirements:

Field

Description

URL

Enter the URL in the format https://login.microsoftonline.com/{tenant ID}. You can get the tenant ID from your Azure application overview. For details, refer to Microsoft’s access tokens guide.

Token Path

Enter the token endpoint path /oauth2/token. If you are using v2, the path looks like this: /oauth2/v2.0/token.

Token Sent Via

For this example, select the Payload option.

Identity Token Sent Via

For this example, select the Header option.

Identity Path

Enter the userinfo endpoint path /openid/userinfo. If you are using v2, the path looks like this: https://graph.microsoft.com/oidc/userinfo.

Authorize Path

Enter the authorization endpoint path /oauth2/authorize. If you are using v2, the path looks like this: /oauth2/v2.0/authorize. For details, see the Microsoft ID tokens guide.

Scope

For this example, enter the scope value as openid profile email. For details, see the userinfo endpoint.

Param Name for access token

For this example, enter the value access_token.

Id

Enter the Azure application’s Application (client) ID value. For example, 9ddab834-xxxx-xxxx-xxxx-818915f043db.

Secret

Enter the Azure application’s client secret value. For example, 7Cz8Q~EphyoaSjmxxxxxxxxxxxxxxxdTqu3KEaaB.

Login Style

Select the type of the login screen. The options are:

  • Redirect

  • Popup

  • Default

Button Text

Enter the text that will be displayed on the login button. For example, Login with Microsoft.

Button Text Color

Enter the color of the login text. For example, #FFFFFF.

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

Enter the color of the login button. For example, #1d74f5.

Key Field

Select the field with which users can log in and which will maintain unique user IDs. The options are:

  • Username

  • Email

In this example, select the Email option.

Username field

Enter the supported username claim key. Note that the supported claims may differ for v1 and v2. Refer to the userinfo endpoint for details.

Email field

Enter the supported email claim key. For example, email.

Name field

Enter the supported name claim key. For example, given_name, family_name, or name.

After saving, you will find the O365 OAuth button on the login and signup page. Simply sign in to your Microsoft account to authenticate!

Rocket.Chat uses the identity path (userinfo) endpoint to get the information on roles. Since the MS Office 365 identity path endpoint does not return this information, the roles cannot be synced with Rocket.Chat currently.