# Add Microsoft Azure Entra ID as a social connection

**Before you start**

- [A Clerk app is required.](https://clerk.com/docs/getting-started/quickstart/setup-clerk.md)
- [A Microsoft Azure account is required.](https://azure.microsoft.com/en-us/free/)

Enabling OAuth with Microsoft Azure Entra ID (formerly [Active Directory](https://learn.microsoft.com/en-us/entra/fundamentals/new-name)) allows your users to sign up and sign in to your Clerk app with their Microsoft account.

## Configure for your development instance

For _development instances_, Clerk uses preconfigured shared OAuth credentials and redirect URIs—no other configuration is needed.

1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/~/user-authentication/sso-connections) page.
2. Select **Add connection** and select **For all users**.
3. Select **Microsoft** from the provider list.

## Configure for your production instance

For _production instances_, you must provide custom credentials. If you already [configured Microsoft as an EASIE connection](https://clerk.com/docs/guides/configure/auth-strategies/enterprise-connections/easie/microsoft.md), you can skip this step. EASIE SSO will automatically use the credentials you configured for your enterprise connection.

To make the setup process easier, it's recommended to keep two browser tabs open: one for the [Clerk Dashboard](https://dashboard.clerk.com/~/user-authentication/sso-connections) and one for your [Microsoft Azure portal](https://portal.azure.com).

1. ### Enable Microsoft as a social connection

   1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/~/user-authentication/sso-connections) page.
   2. Select **Add connection** and select **For all users**.
   3. Select **Microsoft** from the provider list.
   4. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on.
   5. Save the **Redirect URI** somewhere secure. Keep this page open.
2. ### Create a Microsoft Entra ID app

   > If you already have a Microsoft Entra ID app you'd like to connect to Clerk, select your app from the [Microsoft Azure portal](https://portal.azure.com/#home) and skip to [the next step in this tutorial](#get-your-client-id-and-client-secret).

   1. On the homepage of the [Microsoft Azure portal](https://portal.azure.com/#home), in the **Azure services** section, select **[Microsoft Entra ID](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/Overview)**.
   2. In the sidenav, open the **Manage** dropdown and select **[App registrations](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps)**.
   3. Select **New Registration**. You'll be redirected to the **Register an application** page.
   4. Complete the form as follows:
      1. Under **Name**, enter your app name.
      2. Under **Supported account types**, select **Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)**.
      3. Under **Redirect URI (Optional)**, select **Web** as the platform and enter the **Redirect URI** you saved from the Clerk Dashboard.
      4. Select **Register** to submit the form. You'll be redirected to the **Overview** page of your new app. Keep this page open.
3. ### Get your Client ID and Client Secret

   1. From your app's **Overview** page, save the **Application (client) ID** somewhere secure.
   2. In the sidenav, open the **Manage** dropdown and select **Certificates & secrets**.
   3. Select **New client secret**.
   4. In the modal that opens, enter a description and set an expiration time for your secret.
      > Microsoft requires an expiration time for client secrets. The default is 6 months, and the maximum is 24 months. When your secret expires, your social connection will stop working until you generate a new secret. It's recommended to set a reminder before the expiration date to avoid disruption to your sign-in flow.
   5. Select **Add**.
   6. Save the **Value** somewhere secure.
4. ### Enable OpenID

   1. In the left sidenav, open the **Manage** dropdown and select **Authentication (Preview)**.
   2. Select the **Settings** tab.
   3. In the **Front-channel logout URL** field, paste the **Redirect URI** you copied from the Clerk Dashboard.
   4. Under **Implicit grant and hybrid flows**, toggle on both **Access tokens (used for implicit flows)** and **ID tokens (used for implicit and hybrid flows)**.
   5. Select **Save** to save the changes.
5. ### Secure your app against the nOAuth vulnerability

   [nOAuth](https://www.descope.com/blog/post/noauth) is an exploit in Microsoft Entra ID OAuth apps that can lead to account takeovers via email address spoofing. Clerk mitigates this risk by enforcing stricter checks on verified email addresses.

   For further security, Microsoft offers an optional `xms_edov` [claim](https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims-reference), which provides additional context to determine whether the returned email is verified.

   > When adding the `xms_edov` claim in the Azure portal, you may see a warning saying it's invalid or not recognized. You can safely ignore this warning - `xms_edov` is fully supported and documented by Microsoft Entra ID for stronger email domain verification, but the Azure portal's token configuration UI may not recognize it yet.

   To enable it, you must:

   1. In the left sidenav, in the **Manage** dropdown, select **Token configuration**.
   2. Select **Add optional claim**.
   3. For the **Token type**, select **ID**. Then, in the table that opens, enable the `email` and `xms_pdl` claims.
   4. At the bottom of the modal, select **Add**. A new modal will prompt you to turn on the Microsoft Graph email permission. Enable it, then select **Add** to complete the form.
   5. Repeat the previous steps but for **Token type**, select **Access** instead of **ID**. The **Optional claims** list should now show two claims for `email` and two for `xms_pdl`: one each for **ID** and **Access**.
   6. In the left sidenav, in the **Manage** dropdown, select **Manifest**.
   7. In the text editor, search for `"acceptMappedClaims"` and set its value from `null` to `true`.
   8. Search for `"optionalClaims"`, where you'll find the `idToken` and `accessToken` arrays. Each array has an object with the name `xms_pdl`. Change the name to `xms_edov`.
   9. At the top of the page, select **Save**.
   10. In the left sidenav, in the **Manage** dropdown, select **Token configuration** to confirm that the **Optional claims** list includes two claims for `email` and two for `xms_edov`: one each for **ID** and **Access**.

   With these steps complete, Microsoft will send the `xms_edov` claim in the token, which Clerk will use to determine whether the email is verified, even when used with Microsoft Entra ID.
6. ### Set the Client ID and Client Secret in the Clerk Dashboard

   1. Navigate back to the Clerk Dashboard where the configuration page should still be open. Paste the **Client ID** and **Client Secret** values that you saved into the respective fields.
   2. Select **Save**.

   > If the page is no longer open, navigate to the [**SSO connections**](https://dashboard.clerk.com/~/user-authentication/sso-connections) page in the Clerk Dashboard. Select the connection. Under **Use custom credentials**, paste the values into their respective fields.
7. ### Test your connection

   The simplest way to test your connection is to visit your Clerk app's [Account Portal](https://clerk.com/docs/guides/account-portal/overview.md), which is available for all Clerk apps out-of-the-box.

   1. In the Clerk Dashboard, navigate to the [**Account Portal**](https://dashboard.clerk.com/~/account-portal) page.
   2. Next to **Sign-in**, select the button to visit the sign-in page. The URL should resemble:
      - **For development** - `https://your-domain.accounts.dev/sign-in`
      - **For production** - `https://accounts.your-domain.com/sign-in`
   3. Sign in with your connection's credentials.

## Limitations

- Currently, Clerk supports only the `common` tenant type, which allows sign-ins both from organization members and public Microsoft users.
  - The option to selecting the desired tenant type (`common`, `organizations`, `consumers` or specific tenant ID) will be available in an upcoming version of Clerk.
- Only credentials of type `secret` are supported (not the `certificate` type).

> If you're using [SAML with Microsoft](https://clerk.com/docs/guides/configure/auth-strategies/enterprise-connections/saml/azure.md), the different tenant types _are_ supported, and you can disregard these limitations.

---

## Sitemap

[Overview of all docs pages](https://clerk.com/docs/llms.txt)