# Add Microsoft as an EASIE connection

**Before you start**

- [Upgrade to a paid plan](https://clerk.com/pricing)
- [Enable email for your app.](https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options.md)
- [A Microsoft Azure account is required.](https://azure.microsoft.com/en-us/free/)

Enabling [EASIE SSO](https://clerk.com/docs/guides/configure/auth-strategies/enterprise-connections/overview.md#easie) with Microsoft (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 application with their Microsoft account.

## Configure for your development instance

For _development instances_, Clerk uses preconfigured shared 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 specific domains or organizations**.
3. Under **EASIE**, select **Microsoft**.
4. Enter the **Domain**. This is the email domain of the users you want to allow to sign in to your application. Optionally, select an **Organization**.
5. Select **Add connection**.

## Configure for your production instance

For _production instances_, you must provide custom credentials. If you already [configured Microsoft as a social provider](https://clerk.com/docs/guides/configure/auth-strategies/social-connections/microsoft.md), you can skip this step. EASIE SSO will automatically use the credentials you configured for your social 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 an EASIE 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 specific domains or organizations**.
   3. Under **EASIE**, select **Microsoft**.
   4. Enter the **Domain**. This is the email domain of the users you want to allow to sign in to your application. Optionally, select an **Organization**.
   5. Save the **Redirect URI** somewhere secure. Keep this modal and 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.

---

## Sitemap

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