Add Microsoft Azure Entra ID as a social connection

Create a Microsoft Entra ID app

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.
   4. 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 Azure portal, you'll be redirected to its Overview.

1. From your app's overview, save the Application (client) ID somewhere secure. You'll need it to connect your Microsoft Entra ID app to your Clerk app.
2. Under Client credentials, select Add a certificate or secret to generate a Client Secret. You'll be redirected to the Certificate & secrets page.
3. Select New client secret. In the modal that opens, enter 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. Save the new client secret's Value somewhere secure. You'll add this and your client ID to your Clerk app later. Keep this page open.

Connect your Entra ID app and get your redirect URI

1. In the Clerk Dashboard, navigate to the SSO Connections page.
2. Select Add connection and select For all users.
3. In the Choose provider dropdown, select Microsoft.
4. Ensure that both Enable for sign-up and sign-in and Use custom credentials are toggled on. Then:
   • Under Client ID, paste the value you copied from Application (client) ID in the Microsoft Azure portal.
   • Under Client Secret, paste the client secret value you generated.
   • Save the Redirect URI somewhere secure.
   • Select Add connection.

Enable OpenID

To connect your Clerk app to your Microsoft app, set the Redirect URI in your Microsoft Azure portal.

1. Navigate back to the Microsoft Azure portal.
2. In the sidebar, open the Manage dropdown and select Authentication.
3. Select Add a platform.
4. Select Web.
5. In the Redirect URIs field and the Front-channel logout URL field, paste the Redirect URI you copied from the Clerk Dashboard.
6. Under Implicit grant and hybrid flows, check both Access tokens and ID tokens.
7. Select Configure to save the changes.

Test your OAuth

The simplest way to test your OAuth 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 development – https://your-domain.accounts.dev/sign-in
• For production – https://accounts.your-domain.com/sign-in

1. Sign in with your Microsoft account.

Secure your app against the nOAuth vulnerability

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 this optional claim, you must:

1. In the Microsoft Azure portal, navigate to your app.
2. In the sidebar, select Token configuration.
3. Select Add optional claim.
4. For the Token type, select ID. Then, in the table that opens, enable the email and xms_pdl claims.
5. 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.
   Note

   At the time of writing, the xms_edov claim is still in preview and may not be available for all apps. We'll choose another claim and rename it in the manifest later.

6. Repeat the previous steps for Token type, but 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.
7. In the sidebar, go to Manifest.
8. In the text editor, search for "acceptMappedClaims" and set 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 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.