diff --git a/docs/authentication/social-connections/microsoft.mdx b/docs/authentication/social-connections/microsoft.mdx index 9106d0c683..2f10208a3c 100644 --- a/docs/authentication/social-connections/microsoft.mdx +++ b/docs/authentication/social-connections/microsoft.mdx @@ -21,7 +21,7 @@ description: Learn how to allow users to sign up and sign in to your Clerk app w - Protect your app from [the nOAuth exploit](https://www.descope.com/blog/post/noauth). -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 application with their Microsoft account. +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 @@ -50,46 +50,44 @@ To configure your production instance, follow these steps: 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)**. 1. In the sidebar, under **Manage**, select **[App registrations](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps)**. - 1. Select **New Registration**. You'll be taken to the **Register an application** page. - 1. Fill out the form as follows: - 1. Under **Name**, name the app whatever you'd like. "Clerk Demo App", for example. + 1. Select **New Registration**. You'll be redirected to the **Register an application** page. + 1. Complete the form as follows: + 1. Under **Name**, name your app. 1. Under **Supported account types**, select **Accounts in any organizational directory (Any Microsoft Entra ID tenant – Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)**. 1. Under **Redirect URI (Optional)**, select **Web**. - 1. Finally, select **Register** to submit the form. + 1. 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 taken to its **Overview**. + 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, copy the **Application (client) ID** and save it somewhere secure. It's required for connecting your Microsoft Entra ID app to your Clerk app. - 1. 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. + 1. From your app's overview, copy the **Application (client) ID** and save it securely. You'll need it to connect your Microsoft Entra ID app to your Clerk app. + 1. Under **Client credentials**, select **Add a certificate or secret** to generate a Client Secret. You'll be redirected to the **Certificate & secrets** page. 1. Select **New client secret**. 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. - 1. Copy your new client secret's **Value** and save it somewhere secure. You'll add it to your Clerk app later, alongside your client ID. - 1. Leave this tab open. + 1. Copy your new client secret's **Value** and save it securely. 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. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). - 1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. - 1. Select **Add connection**, and select **For all users**. + 1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. + 1. Select **Add connection** and select **For all users**. 1. In the **Choose provider** dropdown, select **Microsoft**. 1. 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 Azure portal. - - Under **Client Secret**, add the client secret value you generated in the Microsoft Azure portal. - - Copy the **Authorized redirect URI**. You need it for the final step to configure your Entra ID app. + - Under **Client Secret**, add the client secret value you generated. + - Copy the **Authorized redirect URI**. You'll need it for the final step to configure your Entra ID app. - Select **Add connection**. ### Enable OpenID - To connect your Clerk app to your Microsoft app, you must set the **Authorized redirect URI** in your Microsoft Azure portal. + To connect your Clerk app to your Microsoft app, set the **Authorized redirect URI** in your Microsoft Azure portal. - 1. Return to the tab where your Microsoft Azure portal is open. - 1. In the sidebar, under **Manage**,select **Authentication**. + 1. Navigate back to the Microsoft Azure portal. + 1. In the sidebar, under **Manage**, select **Authentication**. 1. Select **Add a platform**. 1. Select **Web**. - 1. In the **Redirect URIs** field and the **Front-channel logout URL** field, add the **Authorized redirect URI** you copied in the previous step. + 1. In the **Redirect URIs** field and the **Front-channel logout URL** field, add the **Authorized redirect URI** you copied earlier. 1. Under **Implicit grant and hybrid flows**, check both **Access tokens** and **ID tokens**. 1. Select **Configure** to save the changes. @@ -97,42 +95,44 @@ To configure your production instance, follow these steps: The simplest way to test your OAuth is to visit your Clerk app's [Account Portal](/docs/customization/account-portal/overview), which is available for all Clerk apps out-of-the-box. - 1. In the navigation sidebar of the Clerk Dashboard, select [**Account Portal**](https://dashboard.clerk.com/last-active?path=account-portal). + 1. In the Clerk Dashboard, navigate to the [**Account Portal**](https://dashboard.clerk.com/last-active?path=account-portal) page. 1. 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. On the sign-in page, you should see **Microsoft** as an option. Use it to sign in with your Microsoft account. + + - **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](https://www.descope.com/blog/post/noauth) is an exploit in Microsoft Entra ID OAuth apps that can lead to full account takeovers via email address spoofing. To protect users, Clerk enforces stricter checks on verified email addresses. + [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 has an optional `xms_edov` claim, which provides additional context to that can be used to determine whether the returned email is verified. + 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. Navigate to your Azure application in the Microsoft Azure portal. + 1. In the Microsoft Azure portal, navigate to your app. 1. In the sidebar, select **Token configuration**. 1. Select **Add optional claim**. 1. For the **Token type**, select **ID**. Then, in the table that opens, enable the `email` and `xms_pdl` claims. - 1. At the bottom of the modal, select **Add**. A modal will open asking you to **Turn on the Microsoft Graph email permission**. Enable it, then select **Add** to complete the form. + 1. 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 one from the list and we'll rename it later on in the manifest. - 1. 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**. + > 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. + 1. 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**. 1. In the sidebar, go to **Manifest**. - 1. In the text editor, search for `"acceptMappedClaims"` and change its value from `null` to `true`. - 1. 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`. + 1. In the text editor, search for `"acceptMappedClaims"` and set its value from `null` to `true`. + 1. 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`. 1. At the top of the page, select **Save**. - 1. 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**. + 1. 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, and Clerk will use it to determine whether the email is verified or not, even if it is used with Microsoft Entra ID. + 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. ## Limitations -- Currently Clerk supports only the `common` tenant type, which is intended for allowing sign-ins both from organization members and public Microsoft users. - - Selecting the desired tenant type (`common`, `organizations`, `consumers` or specific tenant ID) will become available in an upcoming version of Clerk. -- Only credentials of type `secret` are currently supported (not the `certificate` type). +- 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). > [!TIP] -> If you are using [SAML with Microsoft](/docs/authentication/saml/azure), the different tenant types _are_ supported and you can disregard these limitations. +> If you're using [SAML with Microsoft](/docs/authentication/saml/azure), the different tenant types _are_ supported, and you can disregard these limitations.