feat: Add docs for third party OIDC providers

docs/authentication/enterprise-connections/oidc/custom-provider.mdx

@@ -17,7 +17,7 @@ description: Learn how to integrate a custom OIDC provider with Clerk for Enterp
     },
   ]}
 >
-  - Use a custom OIDC provider to authenticate users with Enterprise SSO
+  - Add a custom OIDC provider to authenticate users with Enterprise SSO
 </TutorialHero>
 
 This guide explains how to use a custom [OpenID Connect (OIDC)](https://openid.net/developers/how-connect-works) provider to authenticate users via Enterprise SSO.
@@ -29,33 +29,48 @@ To make the setup process easier, it's recommended to keep two browser tabs open
 
   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 specific domains**.
-  1. Under **Third party**, select **OIDC**.
+  1. Under **Third party**, select **OpenID Connect (OIDC)**.
   1. Add the **Name** of the connection.
   1. Add the **Key** of the provider. This is the provider's unique identifier (cannot be changed after creation).
   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 app.
   1. Select **Add connection**. You will be redirected to the connection's configuration page.
 
-  The next steps involve configuring both your IdP and Clerk. Keep both dashboards open as you'll need to reference them.
-
   ### Configure your IdP
 
   1. If necessary, create a new app in your IdP.
-  1. In the connection's configuration page in the Clerk Dashboard, copy the **Authorized redirect URI**.
+  1. In the Clerk Dashboard, navigate to the connection's settings page.
+  1. Copy the **Authorized redirect URI**.
   1. Add the value to your IdP's whitelisted URLs.
 
   ### Set the Discovery Endpoint, Client ID, and Client Secret in Clerk
 
-  1. In your IdP settings, copy your application's **Discovery Endpoint**, **Client ID**, and **Client Secret**.
-  1. In the connection's configuration page in the Clerk Dashboard, paste these values in their respective fields.
-  1. Add the minimum required scopes based on the IdP's documentation. Common OIDC scopes include `openid`, `email`, and `profile`.
+  Most IdPs provide a **Discovery Endpoint** to retrieve metadata about an OIDC provider. If your IdP doesn't offer this endpoint or if you need greater control over the setup process, select **Use Manual Configuration** in the **Identity Provider Configuration** section to manually configure the connection.
+
+  1. In the Clerk Dashboard, navigate to the connection's settings page.
+  1. Copy your application's **Discovery Endpoint**, **Client ID**, and **Client Secret**.
+  1. In the connection's settings page in the Clerk Dashboard, under **Identity Provider Configuration**, paste the values in their respective fields.
+  1. Under **Scopes**, add the minimum required scopes based on the IdP's documentation if needed. Common OIDC scopes include `openid`, `email`, and `profile`.
   1. Select **Save**.
 
   ### Configure attribute mapping (optional)
 
-  If your provider returns claims in a non-standard format, use the **Attribute Mapping** section on the connection's configuration page to adjust the mapping of Clerk's user properties to match the IdP's claim attributes. Important Clerk user properties include `email`, `firstName`, and `lastName`.
+  Attribute mapping allows you to map the IdP's claims with Clerk's user properties such as the `email_verified`. OIDC Enterprise connections require the [`email_verified` claim](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims:~:text=Section%C2%A05.7.-,email_verified,-boolean) to verify email ownership. However, some IdPs, such as Microsoft Azure Active Directory, might not return this claim or use a non-standard format.
+
+  To enable attribute mapping:
+
+  1. In the Clerk Dashboard, navigate to the **Connection** tab of the connection's settings page.
+  1. In the **Attribute Mapping** section, under the **Email address verified** field:
+
+  - If the IdPs that provide the value, enter `email_verified`.
+  - For IdPs that do not provide the value, enter `xms_edov`.
+
+  1. Set **Default value** to **True**.
+  1. Select **Save**.
 
-  > [!CAUTION]
-  > OIDC Enterprise connections require the `email_verified` claim to verify email ownership. If the IdP doesn't return this claim, you can set its default value of `true`. However, ensure you fully trust the IdP to prevent exploits like [nOAuth](https://www.descope.com/blog/post/noauth).
+  > [!WARNING]
+  > If the IdP doesn't return this claim, you can either leave the **Email address verified** field blank or set the **Default value** to `True`. This should only be done if you fully trust the IdP, as it can expose your app to [OAuth attacks](https://www.descope.com/blog/post/noauth).
+  >
+  > For Microsoft Azure Active Directory connections: Use the [`xms_edov` claim](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) to verify email ownership, as Microsoft might not return the standard `email_verified` claim.
 
   ### Allow additional identifiers (optional)