OAuth with Microsoft Azure Entra ID

Create a Microsoft Entra ID app

1. Under the Azure services section on the homepage of the Azure portal, select Microsoft Entra ID.
2. In the sidebar, select App registrations.
3. Select New Registration. You'll be taken to the Register an application page.
4. Fill out the form as follows:
   1. Under Name, name the app whatever you'd like. "Clerk Demo App", for example.
   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.
   4. Finally, select Register to submit the form.

Get your client ID and client secret

Once your Microsoft Entra ID app is created, or once you select your app from the Microsoft Entra ID dashboard, you'll be taken to its Overview.

1. From your app's overview, copy the Application (client) ID and save it somewhere secure. It's required connecting your Microsoft Entra ID app to your Clerk app.
2. On this same page, under Client credentials, select Add a certificate or secret to generate a Client Secret. You'll be taken to the Certificate & secrets page.
3. Select the New client secret button. In the modal that opens, add a description and set an expiration time for your secret.
   Important

   When your secret expires, your social connection will stop working until you generate a new client secret and add it to your Clerk app.

4. Copy your new client secret's Value and save it somewhere secure. You'll add it to your Clerk application later, alongside your client ID.

Connect your Entra ID app and get your redirect URI

1. In another tab, visit the Clerk Dashboard.
2. In the navigation sidebar, go to User & Authentication > Social Connections.
3. In the list of Auth Providers, enable Microsoft.
4. Ensure that both Enable for sign-up and sign-in and Use custom credentials are toggled on. Then:
   • Under Client ID, add the value you copied from Application (client) ID in the Microsoft Entra ID dashboard.
   • Under Client Secret, add the client secret value you generated in the Microsoft Entra ID dashboard.
   • Copy the Authorized redirect URI. You need it for the final step to configure your Entra ID app.
   • Select Save.

Enable OpenID

To connect your Clerk app to your Microsoft app, you must set the Authorized redirect URI in your Microsoft Entra ID dashboard.

1. Return to the tab where your Microsoft Entra ID dashboard is open.
2. In the sidebar, select Authentication, then select Add a platform.
3. Select Single-page application.
4. In the Redirect URIs field of the modal that appears, add your Clerk application's authorized redirect URI. Do the same in the Front-channel logout URL field.

Test your OAuth

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

1. In the navigation sidebar of the Clerk Dashboard, select Account Portal.
2. Next to the Sign-in URL, select Visit. The URL should resemble:
   • For development – https://your-domain.accounts.dev/sign-in
   • For production – https://accounts.your-domain.com/sign-in
3. On the sign-in page, you should see Continue with Microsoft as an option. Use it to sign in with your Microsoft account.

Secure your app against the nOAuth vulnerability

nOAuth is an exploit in Microsoft Entra ID OAuth applications that can lead to full account takeovers via email address spoofing. To protect users, Clerk enforces stricter checks on verified email addresses.

For further security, Microsoft has an optional xms_edov claim, which provides additional context to that can be used to determine whether the returned email is verified.

To enable this optional claim, you must:

1. Navigate to your Azure application in the Microsoft Entra ID dashboard.
2. In the sidebar, select Token configuration.
3. Select Add optional claim.
4. For the Token type, select ID. Then, in the checklist that appears, enable the email and xms_pdl claims.
5. At the bottom of the modal, select the Add button. A modal will appear asking you to Turn on the Microsoft Graph email permission. Enable it, then select Add to complete the form.
   Note

   At the time of writing, the xms_edov claim is still in preview, and may not be available for all applications. So we'll choose another one from the list and we'll rename it later on in the manifest.

6. Repeat the previous steps, but for the Token type, select Access instead of ID. When you're done, the list of Optional claims on this page should have two claims for email and two for xms_pdl: one each for ID and Access.
7. In the sidebar, go to Manifest.
8. In the text editor, search for "acceptMappedClaims" and change its value from null to true.
9. 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.
10. At the top of the page, select Save.
11. In the sidebar, navigate back to Token configuration and confirm that the list of Optional claims 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, and Clerk will use it to determine whether the email is verified or not, even if it is used with Microsoft Entra ID.