update guide

docs/authentication/saml/azure.mdx

@@ -17,77 +17,83 @@ description: Learn how to allow users to sign into your Clerk app with their Mic
     }
   ]}
 >
-  - Use Microsoft Azure Entra ID (formerly [Active Directory](https://learn.microsoft.com/en-us/entra/fundamentals/new-name)) to enable single sign-on (SSO) via SAML for your Clerk application.
+  - Use Microsoft Azure Entra ID to enable SSO via SAML for your Clerk application.
 </TutorialHero>
 
-## Tutorial
+Enabling single sign-on (SSO) 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.
+
+## 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.
+
+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) page.
 
 <Steps>
   ### Set up an enterprise connection in Clerk
 
   To create a SAML connection in Clerk:
 
-  1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections).
+  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 specific domains**.
-  1. Select **Microsoft Entra ID (Formerly AD)** as the identity provider.
-  1. Add the **Name** of the connection. This is the name that will be displayed in the sign-in form.
-  1. Add the **Specific Domain** that you want to allow this connection for. This is the domain of the users you want to allow to sign in to your application.
+  1. Select **Add connection**, and select **For specific domains**.
+  1. In the modal that appears, select **Microsoft Entra ID (Formerly AD)** as the identity provider.
+  1. Add the **Name** of the connection. This is the name that will be displayed on the sign-in form.
+  1. Enter the **Specific Domain** that you want to allow this connection for. This is the domain of the users you want to allow to sign in to your application.
   1. Select **Add connection**. You will be redirected to the connection's configuration page.
   1. Find the **Service Provider Configuration** section.
-  1. Save the **Reply URL (Assertion Consumer Service URL)** and the **Identifier (Entity ID)** values somewhere secure. You'll need these in the [Configure your service provider](#configure-your-service-provider) step.
-  1. Leave this page open.
+  1. Save the **Reply URL (Assertion Consumer Service URL)** and the **Identifier (Entity ID)** values somewhere secure. You'll need these in the [Configure your service provider](#configure-your-service-provider) step. Leave this page open.
 
   ### Create a new enterprise application in Microsoft
 
   To create a new enterprise application in Microsoft:
 
-  1. Navigate to the [Microsoft Portal](https://azure.microsoft.com/en-us/get-started/azure-portal) and sign in.
-  1. Under the **Azure Services** section, find and select **Enterprise Applications**. You may have to go to the [**All services**](https://portal.azure.com/#allservices) page and then scroll down to the **Identity** section to find it.
-  1. Select the **New Application** button.
-  1. Select the **Create your own application** button.
-  1. Fill in the **Name**, ensure **Integrate any other application you don't find in the gallery (Non-gallery)** is selected, and select the **Create** button.
+  1. In a separate page, navigate to the [**Microsoft Portal**](https://azure.microsoft.com/en-us/get-started/azure-portal) and sign in.
+  1. Under the **Azure Services** section, find and select **Enterprise applications**. You may have to go to the [**All services**](https://portal.azure.com/#allservices) page and then scroll down to the **Identity** section to find it.
+  1. After being redirected to the **All applications** page, select **New application**.
+  1. In the **Browse Microsoft Entra Gallery** page, select **Create your own application**.
+  1. Enter the **Name** of your application. Ensure the option **Integrate any other application you don't find in the gallery (Non-gallery)** is selected. Select **Create**.
 
   ### Assign selected user or group in Microsoft
 
-  Now that you have created the enterprise application, you need to assign your users/user groups to it. For example, if you were part of the Clerk organization, you would have access to users and groups in the Clerk organization. In this case, you could assign one or more users or entire groups to the enterprise application you just created.
+  Now that you have created the enterprise application, you need to assign users or groups to the application. For example, if you were part of the Clerk organization, you would have access to users and groups within the Clerk organization. In this case, you could assign individual users or entire groups to the enterprise application you just created.
 
-  1. Under the **Getting started** section, select **Assign users and groups**.
-  1. Select the **Add user/group** button.
-  1. Under **Users**, select the **None Selected** link.
-  1. In the search field, enter the user or group of users that you want to assign to the enterprise application.
-  1. Select the check box next to the user or group that you want to assign.
+  1. In the **Getting Started** section, select the **Assign users and groups** link.
+  1. Select **Add user/group**. You will be redirected to the **Add Assignment** page.
+  1. Select the **None Selected** link.
+  1. To assign a user to the enterprise application, you can either use the search field to find a user or select the checkbox next to the user in the table.
   1. Select the **Select** button at the bottom of the page.
-  1. Select the **Assign** button at the bottom of the page.
+  1. You will be redirected to the **Add Assignment** page. Select the **Assign** button at the bottom of the page.
 
-  ### Configure single sign-on (SSO) in Microsoft
+  ### Configure SSO in Microsoft
 
-  After you have assigned the user or group of users to the enterprise application, you need to configure the single sign-on (SSO) settings to enable SAML SSO.
+  After assigning the user or group to the enterprise application, you need to configure the SSO settings to enable SAML SSO.
 
-  1. In the navigation sidebar, select **Manage** and select **Single sign-on**.
-  1. Select **SAML** as the single sign-on method.
+  1. In the navigation sidebar, open the **Manage** dropdown and select **Single sign-on**.
+  1. In the **Select a single sign-on method** section, select **SAML**.
 
   ### Configure your service provider
 
-  To configure your service provider (Clerk), you must add these two fields to your IdP's application:
+  To configure Clerk as your service provider, add these two fields to your IdP's application:
 
-  - **Reply URL (Assertion Consumer Service URL)** - This is your application's URL that your IdP will redirect your users back to after they have authenticated in your IdP.
-  - **Identifier (Entity ID)** - This is a unique identifier for your SAML connection that your IdP application needs.
+  - **Identifier (Entity ID)** - A unique identifier for your SAML connection, required by your IdP application.
+  - **Reply URL (Assertion Consumer Service URL)** - The URL of your application where your IdP will redirect your users after they authenticate.
 
   To fill out the appropriate values for these fields:
 
   1. On the **Set up Single Sign-On with SAML** page, find the **Basic SAML Configuration** section.
-  1. Select the **Edit** button. This will open a **Basic SAML Configuration** modal.
-  1. Paste the **Reply URL (Assertion Consumer Service URL)** and the **Identifier (Entity ID)** values that you saved earlier into their respective fields.
-  1. Select **Save** at the top of the modal.
+  1. Select **Edit** to open the **Basic SAML Configuration** panel.
+  1. Paste the **Identifier (Entity ID)** and **Reply URL (Assertion Consumer Service URL)** values you saved from the previous step into their respective fields. These values will be saved automatically.
+  1. Select **Save** at the top of the panel.
+  1. Once finished, close the panel.
 
   ### Configure your identity provider
 
-  To configure your identity provider (Microsoft Entra ID), you need to add the following fields to your application:
+  To configure Microsoft Entra ID as your identity provider, add the following fields to your application:
 
-  1. Find the **SAML Certificates** section.
-  1. Copy the **App Federation Metadata URL**.
-  1. Navigate back to the Clerk Dashboard. In the **Identity Provider Configuration** section, under **Metadata**, paste the **App Federation Metadata URL**.
+  1. On the **Set up Single Sign-On with SAML** page, find the **SAML Certificates** section.
+  1. Copy the **App Federation Metadata Url**.
+  1. Navigate back to the **Clerk Dashboard**. In the **Identity Provider Configuration** section, under **App Federation Metadata Url**, paste the **App Federation Metadata URL**.
+  1. Select **Fetch & save**.
 
   ### Map Microsoft claims to Clerk attributes
 
@@ -101,16 +107,35 @@ description: Learn how to allow users to sign into your Clerk app with their Mic
 
   The only Microsoft claim that is necessary to map is the email address claim. This is the email address that your users will use to log in to your application.
 
+  1. Navigate back to the **Microsoft Azure Portal**.
   1. On the **Set up Single Sign-On with SAML** page, find the **Attributes & Claims** section.
   1. Select the **Edit** button.
-  1. Select the email address claim (`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`) to edit the field.
-  1. Next to **Source attribute**, select the dropdown and choose `user.userprincipalname`.
+  1. To edit the email claim, select the claim with the value of **`user.email`**. You will be redirected to the **Manage claim** page.
+  1. Next to **Source attribute**, search and select the dropdown and choose **`user.userprincipalname`**.
   1. Select **Save** at the top of the page.
 
   ### Enable the connection for Clerk
 
   To make the connection available for your users to authenticate with:
 
-  1. In the Clerk Dashboard, you should still have the connection's configuration page open. If not, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page and select the connection.
-  1. Toggle on **Enable connection** and select **Save**.
+  1. Navigate back to the **Clerk Dashboard** to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page.
+  1. Under **Connection**, toggle on **Enable connection** and select **Save**.
+
+  ### 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.
+
+  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`
+
+  If you're already signed into your Azure account, clicking either link automatically redirects you to your application.
+
+  If you're not signed in:
+
+  1. Enter the email of the user you assigned to your enterprise application in the sign-in form.
+  1. After being redirecting to Microsoft's login page, enter your password.
+  1. Upon successful login, you will be redirected to your application.
 </Steps>