(/authentication/social-connections/microsoft) ff: update guide (#1607)

Co-authored-by: Alexis Aguilar <[email protected]>

docs/authentication/social-connections/microsoft.mdx

@@ -1,12 +1,12 @@
 ---
 title: Add Microsoft Azure Entra ID as a social connection
-description: Learn how to allow users to sign into your Clerk app with their Microsoft account using OAuth.
+description: Learn how to allow users to sign up and sign in to your Clerk app with their Microsoft account using OAuth.
 ---
 
 <TutorialHero
   beforeYouStart={[
     {
-      title: "A Clerk application is required.",
+      title: "A Clerk app is required.",
       link: "/docs/quickstarts/setup-clerk",
       icon: "clerk",
     },
@@ -18,132 +18,119 @@ description: Learn how to allow users to sign into your Clerk app with their Mic
   ]}
 >
   - Use Microsoft Azure Entra ID to authenticate users with OAuth.
-  - Protect your application from [the nOAuth exploit](https://www.descope.com/blog/post/noauth).
+  - Protect your app from [the nOAuth exploit](https://www.descope.com/blog/post/noauth).
 </TutorialHero>
 
-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 in and sign up 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
 
-For _development instances_, Clerk uses preconfigured shared OAuth credentials and redirect URIs — no other configuration is needed.
+For _development instances_, Clerk uses preconfigured shared OAuth credentials and redirect URIs—no other configuration is needed.
 
 To configure your development instance, follow these steps:
 
-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 the **Add connection** button, 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. Select **Add connection**.
 
 ## Configure for your production instance
 
-In _production instances_, you must provide custom credentials, which involves generating your own **Client ID** and **Client Secret** using your Microsoft Entra ID dashboard account.
+In _production instances_, you must provide custom credentials, which involves generating your own **Client ID** and **Client Secret** using your Microsoft Entra ID account.
 
 To configure your production instance, follow these steps:
 
 <Steps>
   ### 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 Entra ID dashboard](https://portal.azure.com/#home) and skip to [the next step in this tutorial](#get-your-client-id-and-client-secret).
+  > 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 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. 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, open the **Manage** dropdown and select **[App registrations](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps)**.
+  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 Entra ID dashboard, 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. Select the **New client secret** button. In the modal that opens, add a description and set an expiration time for your secret.
+  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 application 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 the **Add connection** button, 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 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.
+     - 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.
+     - Save the **Authorized redirect URI** somewhere secure.
      - Select **Add connection**.
 
   ### Enable OpenID
 
-  To connect your Clerk app to your Microsoft app, you must set the **Authorized redirect URI** in your Microsoft Entra ID dashboard.
+  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 Entra ID dashboard is open.
-  1. In the sidebar, under **Manage**,select **Authentication**.
+  1. Navigate back to the Microsoft Azure portal.
+  1. In the sidebar, open the **Manage** dropdown and 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 from the Clerk Dashboard.
   1. Under **Implicit grant and hybrid flows**, check both **Access tokens** and **ID tokens**.
   1. Select **Configure** to save the changes.
 
   ### Test your OAuth
 
-  The simplest way to test your OAuth is to visit your Clerk application's [Account Portal](/docs/customization/account-portal/overview), which is available for all Clerk applications out-of-the-box.
+  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 applications 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 Entra ID dashboard.
+  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 checklist that appears, enable the `email` and `xms_pdl` claims.
-  1. 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.
+  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 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 applications. So 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.
 </Steps>
 
 ## 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.
-
-## Next steps
-
-<Cards>
-  - [SAML SSO with Microsoft Azure AD](/docs/authentication/saml/azure)
-  - Learn how to integrate Microsoft Azure AD with Clerk using SAML SSO.
-
-  ---
-
-  - [Account Linking](/docs/authentication/social-connections/account-linking)
-  - Learn how Clerk handles account linking and manages unverified email addresses from social providers.
-</Cards>
+> If you're using [SAML with Microsoft](/docs/authentication/saml/azure), the different tenant types _are_ supported, and you can disregard these limitations.