Skip to main content
Docs

Add Microsoft as an EASIE connection

You will learn the following:

  • Use Microsoft to authenticate users with EASIE SSO.

Enabling EASIE SSO with Microsoft (formerly Active Directory) 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 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, 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 and one for your Microsoft Azure portal.

Enable Microsoft as an EASIE connection

  1. In the Clerk Dashboard, navigate to the 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.

Create a Microsoft Entra ID app

Tip

If you already have a Microsoft Entra ID app you'd like to connect to Clerk, select your app from the Microsoft Azure portal and skip to the next step in this tutorial.

  1. On the homepage of the Microsoft Azure portal, in the Azure services section, select Microsoft Entra ID.
  2. In the sidebar, open the Manage dropdown and select App registrations.
  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.
  1. From your app's Overview page, save the Application (client) ID somewhere secure.
  2. In the sidebar, 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.

    Warning

    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.
  1. In the left sidebar, open the Manage dropdown and select Authentication.
  2. In the Front-channel logout URL field, paste the Redirect URI you copied from the Clerk Dashboard.
  3. Under Implicit grant and hybrid flows, check both Access tokens and ID tokens.
  4. Select Save to save the changes.

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, which provides additional context to determine whether the returned email is verified.

To enable it, you must:

  1. In the left sidebar, 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 sidebar, 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 sidebar, 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.

  1. Navigate back to the Clerk Dashboard where the modal should still be open. Paste the Client ID and Client Secret values that you saved into the respective fields.
  2. Select Add connection.

Note

If the modal or page is no longer open, navigate to the SSO connections page in the Clerk Dashboard. Select the connection. Under Use custom credentials, paste the values into their respective fields.

The simplest way to test your connection is to visit your Clerk app's Account Portal, which is available for all Clerk apps out-of-the-box.

  1. In the Clerk Dashboard, navigate to the Account Portal page.
  2. Next to the Sign-in URL, select Visit. The URL should resemble:
    • For developmenthttps://your-domain.accounts.dev/sign-in
    • For productionhttps://accounts.your-domain.com/sign-in
  3. Sign in with your connection's credentials.

Feedback

What did you think of this content?

Last updated on