refactor

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,120 +18,121 @@ 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 application 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.
 
-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 **Choose provider** dropdown, search for and select **Microsoft**.
+To configure your development instance, follow these steps:
+
+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** 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 account.
 
-To make the setup process easier, it's recommended to keep two browser tabs open: one for your [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Microsoft Azure portal](https://portal.azure.com).
+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 Azure portal](https://portal.azure.com/#home) homepage 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 [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. 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.
+     1. Under **Name**, name the app whatever you'd like. "Clerk Demo App", for example.
      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.
 
   ### 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** page.
+  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**.
 
   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 redirected to the **Certificate & secrets** page.
-  1. Select **New client secret**. In the panel that opens, add a description and set an expiration time for your secret. Select **Add**.
+  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 **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. 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.
 
-  ### Connect your Microsoft Entra ID app and get your redirect URI
+  ### 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 **Choose provider** dropdown, search for and select **Microsoft**.
+  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**, paste the value you copied from **Application (client) ID** the Microsoft Azure portal.
-     - Under **Client Secret**, paste the client secret value you generated from the Microsoft Azure portal.
+     - 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.
      - Select **Add connection**.
 
   ### Enable OpenID
 
-  To connect your Clerk app to your Microsoft Entra ID app, you must set the **Authorized redirect URI** in your Microsoft Azure portal.
+  To connect your Clerk app to your Microsoft app, you must set the **Authorized redirect URI** in your Microsoft Azure portal.
 
-  1. Navigate back to the Microsoft Azure portal.
-  1. In the sidebar, open the **Manage** dropdown and select **Authentication**.
+  1. Return to the tab where your Microsoft Azure portal is open.
+  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, paste the **Authorized redirect URI** you copied in the previous step.
-  1. Under **Implicit grant and hybrid flows**, select both **Access tokens** and **ID tokens**.
+  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. 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. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=account-portal).
-  1. In the top navigation, select **Configure**. In the sidebar, select **Account Portal**.
+  1. In the navigation sidebar of the Clerk Dashboard, select [**Account Portal**](https://dashboard.clerk.com/last-active?path=account-portal).
   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. Sign in with your Microsoft account.
+  1. On the sign-in page, you should see **Microsoft** as an option. Use it to 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 full account takeovers via email address spoofing. To protect users, Clerk enforces stricter checks on verified email addresses.
 
-  For further security, Microsoft offers an optional [**`xms_edov`**](https://learn.microsoft.com/en-us/entra/identity-platform/migrate-off-email-claim-authorization#using-the-xms_edov-optional-claim-to-determine-email-verification-status-and-migrate-users) claim, which provides additional context that can be used to determine whether the returned email is verified.
+  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, follow these steps:
+  To enable this optional claim, you must:
 
-  1. Navigate to your application in the Microsoft Azure portal.
-  1. In the sidebar, open the **Manage** dropdown and select **Token configuration**.
+  1. Navigate to your Azure application in the Microsoft Azure portal.
+  1. In the sidebar, select **Token configuration**.
   1. Select **Add optional claim**.
-  1. For the **Token type**, select **ID**. Then, in the table that appears, enable the `email` and `xms_pdl` claims.
-  1. At the bottom of the panel, select **Add**.
-  1. In the modal that appears, select **Turn on the Microsoft Graph email permission (required for claims to appear in token)** and then select **Add**.
+  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.
      > [!NOTE]
-     > At the time of writing, the `xms_edov` claim is still in preview, and may not be available for all applications. We'll choose another claim from the list and rename it later in the manifest.
-  1. Repeat the previous steps, but this time for **Token type**, select **Access** instead of **ID**. When you're done, the **Optional claims** list on this page should show two claims for `email` and two for `xms_pdl`: one each for **ID** and **Access**.
-  1. In the sidebar, under the **Manage** dropdown, select **Manifest**.
-  1. In the **Microsoft Graph App Manifest** text editor, search for `"acceptMappedClaims"` and change its value from `null` to `true`.
+     > 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**.
+  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. At the top of the text editor, select **Save**.
-  1. In the sidebar, navigate back to **Token configuration**. Confirm that the **Optional claims** list includes two claims for `email` and two for `xms_edov`: one each for **ID** and **Access**.
+  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**.
 
-  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, even when used with Microsoft Entra ID.
+  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.
 </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.
-  - The ability to select a desired tenant type (`common`, `organizations`, `consumers` or specific tenant ID) will be available in a future version of Clerk.
-- Only credentials of type `secret` are supported (not the `certificate` type).
+- 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).
 
 > [!TIP]
-> If you are using [SAML with Microsoft](/docs/authentication/saml/azure), different tenant types _are_ supported and you can disregard these limitations.
+> If you are using [SAML with Microsoft](/docs/authentication/saml/azure), the different tenant types _are_ supported and you can disregard these limitations.