---
title: "Rocket Chat Custom OAuth with Office 365"
slug: "ms-office-365-custom-oauth-setup"
description: "Configure custom OAuth with Office 365 in Rocket Chat. Enable secure login and compliance for enterprise communications."
updated: 2026-10-26T17:14:11Z
published: 2026-10-26T17:14:11Z
canonical: "docs.rocket.chat/ms-office-365-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.

# MS Office 365 Custom OAuth Setup

![](https://cdn.us.document360.io/6ae79a05-7252-45d0-96e8-8f375e07b1b2/Images/Documentation/Premium(14).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.

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](https://www.microsoft.com/en-us/security/business/identity-access/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](https://portal.azure.com/).
- 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](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app).
  - Fill in the details. You will get the redirect URI from your Rocket.Chat workspace when you [Create Custom O365 OAuth](/v1/docs/ms-office-365-custom-oauth-setup#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:

1. Go to **Manage → Workspace** → **Settings** → **OAuth**.
2. Click on **Custom OAuth** and enter a name for the new OAuth integration.
3. 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.
4. 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](https://learn.microsoft.com/en-us/entra/identity-platform/access-tokens). |
| **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](https://learn.microsoft.com/en-us/entra/identity-platform/id-tokens) guide. |
| **Scope** | For this example, enter the scope value as `openid profile email`. For details, see the [userinfo endpoint](https://learn.microsoft.com/en-us/entra/identity-platform/userinfo). |
| **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`. > [!WARNING] > **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](https://learn.microsoft.com/en-us/entra/identity-platform/userinfo) 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!

> [!NOTE]
> **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.**