From 4972ccc8f281d31389a743100a0f4db25e5e41d6 Mon Sep 17 00:00:00 2001 From: vi Date: Tue, 8 Oct 2024 00:25:46 +0200 Subject: [PATCH 01/27] ff --- .../social-connections/microsoft.mdx | 85 +++++++++---------- 1 file changed, 42 insertions(+), 43 deletions(-) diff --git a/docs/authentication/social-connections/microsoft.mdx b/docs/authentication/social-connections/microsoft.mdx index 1993b7be31..bac744b61a 100644 --- a/docs/authentication/social-connections/microsoft.mdx +++ b/docs/authentication/social-connections/microsoft.mdx @@ -21,48 +21,46 @@ description: Learn how to allow users to sign into your Clerk app with their Mic - Protect your application 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 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 in and sign up 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. +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. 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 **Choose provider** dropdown, select **Microsoft**. +1. In the **Choose provider** dropdown, search for and 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: +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). ### 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) homepage 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. 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 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. Under **Name**, name the app whatever you'd like. For example, "Clerk Demo 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. ### 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 taken to its **Overview** page. 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. 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 the **New client secret** button. In the panel that opens, add a description and set an expiration time for your secret. Select **Add**. > [!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. @@ -70,71 +68,72 @@ To configure your production instance, follow these steps: ### 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. 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 **Choose provider** dropdown, select **Microsoft**. + 1. In the **Choose provider** dropdown, search for and 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. + - 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 Microsoft Entra ID. - 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 app, you must set the **Authorized redirect URI** in your Microsoft Entra ID dashboard. + To connect your Clerk app to your Microsoft app, you must set the **Authorized redirect URI** in your Microsoft Entra 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. Under **Implicit grant and hybrid flows**, check both **Access tokens** and **ID tokens**. + 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. 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. - 1. In the navigation sidebar of the Clerk Dashboard, select [**Account Portal**](https://dashboard.clerk.com/last-active?path=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. On the sign-in page, you should see **Microsoft** as an option. Use it to sign in with your Microsoft account. + 1. On the sign-in page, you should see **Microsoft** as an option. Select 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. - 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`**](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. - To enable this optional claim, you must: + To enable this optional claim, follow these steps: - 1. Navigate to your Azure application in the Microsoft Entra ID dashboard. - 1. In the sidebar, select **Token configuration**. + 1. Navigate to your Azure application in the **Microsoft Azure portal**. + 1. In the sidebar, open the **Manage** dropdown and 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 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**. > [!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**. - 1. In the sidebar, go to **Manifest**. - 1. In the 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 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`. 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. 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**. - 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, and Clerk will use it 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 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). > [!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 are using [SAML with Microsoft](/docs/authentication/saml/azure), different tenant types _are_ supported and you can disregard these limitations. ## Next steps From 792817f5eea3d368a35f8b3f9d2610958f021fb8 Mon Sep 17 00:00:00 2001 From: victoria Date: Tue, 8 Oct 2024 19:18:34 +0200 Subject: [PATCH 02/27] Update docs/authentication/social-connections/microsoft.mdx Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> --- docs/authentication/social-connections/microsoft.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/social-connections/microsoft.mdx b/docs/authentication/social-connections/microsoft.mdx index bac744b61a..31d583b3b5 100644 --- a/docs/authentication/social-connections/microsoft.mdx +++ b/docs/authentication/social-connections/microsoft.mdx @@ -49,7 +49,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open 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 taken to the **Register an application** page. 1. Fill out the form as follows: - 1. Under **Name**, name the app whatever you'd like. For example, "Clerk Demo App." + 1. Under **Name**, name the app whatever you'd like. 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. From 7455ed51c67601244ba88f39c5a6206f48d2048d Mon Sep 17 00:00:00 2001 From: victoria Date: Tue, 8 Oct 2024 19:19:09 +0200 Subject: [PATCH 03/27] Update docs/authentication/social-connections/microsoft.mdx Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> --- docs/authentication/social-connections/microsoft.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/social-connections/microsoft.mdx b/docs/authentication/social-connections/microsoft.mdx index 31d583b3b5..1c23f12e3c 100644 --- a/docs/authentication/social-connections/microsoft.mdx +++ b/docs/authentication/social-connections/microsoft.mdx @@ -37,7 +37,7 @@ For _development instances_, Clerk uses preconfigured shared OAuth credentials a 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 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). ### Create a Microsoft Entra ID app From b0a0460f2afcd905d9e0cb89318ebdd8289065de Mon Sep 17 00:00:00 2001 From: victoria Date: Tue, 8 Oct 2024 19:22:12 +0200 Subject: [PATCH 04/27] Update docs/authentication/social-connections/microsoft.mdx Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> --- docs/authentication/social-connections/microsoft.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/social-connections/microsoft.mdx b/docs/authentication/social-connections/microsoft.mdx index 1c23f12e3c..81a70c6b07 100644 --- a/docs/authentication/social-connections/microsoft.mdx +++ b/docs/authentication/social-connections/microsoft.mdx @@ -43,7 +43,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open ### 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) homepage 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)**. From b912c2534367d6210bb15dc6e490affcb9c04e4d Mon Sep 17 00:00:00 2001 From: victoria Date: Tue, 8 Oct 2024 19:31:32 +0200 Subject: [PATCH 05/27] Update docs/authentication/social-connections/microsoft.mdx Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> --- docs/authentication/social-connections/microsoft.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/social-connections/microsoft.mdx b/docs/authentication/social-connections/microsoft.mdx index 81a70c6b07..7b1d07e3db 100644 --- a/docs/authentication/social-connections/microsoft.mdx +++ b/docs/authentication/social-connections/microsoft.mdx @@ -56,7 +56,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open ### 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** page. 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. From d72fe5f067cd55b2863aac9f8fc71aec4b68b139 Mon Sep 17 00:00:00 2001 From: victoria Date: Tue, 8 Oct 2024 19:31:38 +0200 Subject: [PATCH 06/27] Update docs/authentication/social-connections/microsoft.mdx Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> --- docs/authentication/social-connections/microsoft.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/social-connections/microsoft.mdx b/docs/authentication/social-connections/microsoft.mdx index 7b1d07e3db..d635b864eb 100644 --- a/docs/authentication/social-connections/microsoft.mdx +++ b/docs/authentication/social-connections/microsoft.mdx @@ -45,7 +45,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open > [!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). - 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. 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 taken to the **Register an application** page. 1. Fill out the form as follows: From cedfcb8bfcf466e07ff3cbfd7a016205e8484232 Mon Sep 17 00:00:00 2001 From: victoria Date: Tue, 8 Oct 2024 19:31:44 +0200 Subject: [PATCH 07/27] Update docs/authentication/social-connections/microsoft.mdx Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> --- docs/authentication/social-connections/microsoft.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/social-connections/microsoft.mdx b/docs/authentication/social-connections/microsoft.mdx index d635b864eb..aacdae5005 100644 --- a/docs/authentication/social-connections/microsoft.mdx +++ b/docs/authentication/social-connections/microsoft.mdx @@ -66,7 +66,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open 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. - ### Connect your Entra ID app and get your redirect URI + ### Connect your Microsoft 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**. From d74c7531674e74f80292a483354ba81c2eee700a Mon Sep 17 00:00:00 2001 From: victoria Date: Tue, 8 Oct 2024 19:32:49 +0200 Subject: [PATCH 08/27] Update docs/authentication/social-connections/microsoft.mdx Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> --- docs/authentication/social-connections/microsoft.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/social-connections/microsoft.mdx b/docs/authentication/social-connections/microsoft.mdx index aacdae5005..741908a347 100644 --- a/docs/authentication/social-connections/microsoft.mdx +++ b/docs/authentication/social-connections/microsoft.mdx @@ -80,7 +80,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open ### Enable OpenID - To connect your Clerk app to your Microsoft app, you must set the **Authorized redirect URI** in your Microsoft Entra 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**. From e38f502a71b14bd9467c0b8c413c59497d0b7415 Mon Sep 17 00:00:00 2001 From: victoria Date: Tue, 8 Oct 2024 19:32:58 +0200 Subject: [PATCH 09/27] Update docs/authentication/social-connections/microsoft.mdx Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> --- docs/authentication/social-connections/microsoft.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/social-connections/microsoft.mdx b/docs/authentication/social-connections/microsoft.mdx index 741908a347..2bbccf69e1 100644 --- a/docs/authentication/social-connections/microsoft.mdx +++ b/docs/authentication/social-connections/microsoft.mdx @@ -108,7 +108,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open To enable this optional claim, follow these steps: - 1. Navigate to your Azure application in the **Microsoft Azure portal**. + 1. Navigate to your Azure application in the Microsoft Azure portal. 1. In the sidebar, open the **Manage** dropdown and 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. From 4968fbabd5649a91db4df8e3425a5bb857e2e436 Mon Sep 17 00:00:00 2001 From: victoria Date: Tue, 8 Oct 2024 19:33:36 +0200 Subject: [PATCH 10/27] Update docs/authentication/social-connections/microsoft.mdx Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> --- docs/authentication/social-connections/microsoft.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/social-connections/microsoft.mdx b/docs/authentication/social-connections/microsoft.mdx index 2bbccf69e1..86d02aca20 100644 --- a/docs/authentication/social-connections/microsoft.mdx +++ b/docs/authentication/social-connections/microsoft.mdx @@ -68,7 +68,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open ### Connect your Microsoft 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. 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 **Choose provider** dropdown, search for and select **Microsoft**. From fba3e902fd7f876e76d7734beeaab2d4e646abd0 Mon Sep 17 00:00:00 2001 From: victoria Date: Tue, 8 Oct 2024 19:33:45 +0200 Subject: [PATCH 11/27] Update docs/authentication/social-connections/microsoft.mdx Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> --- docs/authentication/social-connections/microsoft.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/social-connections/microsoft.mdx b/docs/authentication/social-connections/microsoft.mdx index 86d02aca20..5b9d7e72a3 100644 --- a/docs/authentication/social-connections/microsoft.mdx +++ b/docs/authentication/social-connections/microsoft.mdx @@ -74,7 +74,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. In the **Choose provider** dropdown, search for and 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 Microsoft Entra ID. + - Under **Client Secret**, paste the client secret value you generated from 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**. From 2d5cbb19122b8b767401432ffbb10d7537f2f36e Mon Sep 17 00:00:00 2001 From: victoria Date: Tue, 8 Oct 2024 19:33:52 +0200 Subject: [PATCH 12/27] Update docs/authentication/social-connections/microsoft.mdx Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> --- docs/authentication/social-connections/microsoft.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/social-connections/microsoft.mdx b/docs/authentication/social-connections/microsoft.mdx index 5b9d7e72a3..1e4d37588d 100644 --- a/docs/authentication/social-connections/microsoft.mdx +++ b/docs/authentication/social-connections/microsoft.mdx @@ -82,7 +82,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open 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. 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**. From f612501cb84ba7e40e8b1eb444769eac591e98fe Mon Sep 17 00:00:00 2001 From: victoria Date: Tue, 8 Oct 2024 19:49:07 +0200 Subject: [PATCH 13/27] Update docs/authentication/social-connections/microsoft.mdx Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> --- docs/authentication/social-connections/microsoft.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/social-connections/microsoft.mdx b/docs/authentication/social-connections/microsoft.mdx index 1e4d37588d..0777e7b617 100644 --- a/docs/authentication/social-connections/microsoft.mdx +++ b/docs/authentication/social-connections/microsoft.mdx @@ -94,7 +94,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open 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. 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` From 714c4d6c6b06f651be6d7c12f34f684f6efe794e Mon Sep 17 00:00:00 2001 From: vi Date: Tue, 8 Oct 2024 20:11:36 +0200 Subject: [PATCH 14/27] fix --- docs/authentication/social-connections/microsoft.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/authentication/social-connections/microsoft.mdx b/docs/authentication/social-connections/microsoft.mdx index 0777e7b617..f018080176 100644 --- a/docs/authentication/social-connections/microsoft.mdx +++ b/docs/authentication/social-connections/microsoft.mdx @@ -80,7 +80,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open ### 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 Entra ID 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**. @@ -108,7 +108,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open To enable this optional claim, follow these steps: - 1. Navigate to your Azure application in the Microsoft Azure portal. + 1. Navigate to your application in the Microsoft Azure portal. 1. In the sidebar, open the **Manage** dropdown and 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. From 94232f66f7c7825789f08a9cfb702895d5a4fa16 Mon Sep 17 00:00:00 2001 From: vi Date: Tue, 8 Oct 2024 21:43:02 +0200 Subject: [PATCH 15/27] remove next steps --- docs/authentication/social-connections/microsoft.mdx | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/docs/authentication/social-connections/microsoft.mdx b/docs/authentication/social-connections/microsoft.mdx index f018080176..848778b83f 100644 --- a/docs/authentication/social-connections/microsoft.mdx +++ b/docs/authentication/social-connections/microsoft.mdx @@ -134,15 +134,3 @@ To make the setup process easier, it's recommended to keep two browser tabs open > [!TIP] > If you are using [SAML with Microsoft](/docs/authentication/saml/azure), different tenant types _are_ supported and you can disregard these limitations. - -## Next steps - - - - [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. - From 41e77eefba59e5f6d58bde3f6f4fe44dae97ff7b Mon Sep 17 00:00:00 2001 From: victoria Date: Tue, 8 Oct 2024 21:54:25 +0200 Subject: [PATCH 16/27] Update docs/authentication/social-connections/microsoft.mdx Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> --- docs/authentication/social-connections/microsoft.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/social-connections/microsoft.mdx b/docs/authentication/social-connections/microsoft.mdx index 848778b83f..4a7a4c6ffd 100644 --- a/docs/authentication/social-connections/microsoft.mdx +++ b/docs/authentication/social-connections/microsoft.mdx @@ -29,7 +29,7 @@ For _development instances_, Clerk uses preconfigured shared OAuth credentials a 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. Select **Add connection**, and select **For all users**. 1. In the **Choose provider** dropdown, search for and select **Microsoft**. 1. Select **Add connection**. From 1115aa4c3159665912114b6264eb609c6189b678 Mon Sep 17 00:00:00 2001 From: victoria Date: Tue, 8 Oct 2024 21:54:30 +0200 Subject: [PATCH 17/27] Update docs/authentication/social-connections/microsoft.mdx Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> --- docs/authentication/social-connections/microsoft.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/social-connections/microsoft.mdx b/docs/authentication/social-connections/microsoft.mdx index 4a7a4c6ffd..cc851bdf14 100644 --- a/docs/authentication/social-connections/microsoft.mdx +++ b/docs/authentication/social-connections/microsoft.mdx @@ -60,7 +60,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open 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 the **New client secret** button. In the panel that opens, add a description and set an expiration time for your secret. Select **Add**. + 1. Select **New client secret**. In the panel that opens, add a description and set an expiration time for your secret. Select **Add**. > [!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. From e8884a22af5fcb6408cc42eb68be8c8098b677fd Mon Sep 17 00:00:00 2001 From: victoria Date: Tue, 8 Oct 2024 21:54:35 +0200 Subject: [PATCH 18/27] Update docs/authentication/social-connections/microsoft.mdx Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> --- docs/authentication/social-connections/microsoft.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/social-connections/microsoft.mdx b/docs/authentication/social-connections/microsoft.mdx index cc851bdf14..8f21aa9585 100644 --- a/docs/authentication/social-connections/microsoft.mdx +++ b/docs/authentication/social-connections/microsoft.mdx @@ -70,7 +70,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open 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. Select **Add connection**, and select **For all users**. 1. In the **Choose provider** dropdown, search for and 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. From baf7799abd602c0251e5f98f8e85bbed78c31cd4 Mon Sep 17 00:00:00 2001 From: victoria Date: Tue, 8 Oct 2024 21:54:55 +0200 Subject: [PATCH 19/27] Update docs/authentication/social-connections/microsoft.mdx Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> --- docs/authentication/social-connections/microsoft.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/social-connections/microsoft.mdx b/docs/authentication/social-connections/microsoft.mdx index 8f21aa9585..7f88a3c4e2 100644 --- a/docs/authentication/social-connections/microsoft.mdx +++ b/docs/authentication/social-connections/microsoft.mdx @@ -98,7 +98,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open 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. Select it to sign in with your Microsoft account. + 1. Sign in with your Microsoft account. ### Secure your app against the nOAuth vulnerability From 0c9a296f1501c9381729c7661309931610463e37 Mon Sep 17 00:00:00 2001 From: vi Date: Tue, 8 Oct 2024 22:12:51 +0200 Subject: [PATCH 20/27] update test oauth steps --- docs/authentication/social-connections/microsoft.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/authentication/social-connections/microsoft.mdx b/docs/authentication/social-connections/microsoft.mdx index 7f88a3c4e2..97e83a68e5 100644 --- a/docs/authentication/social-connections/microsoft.mdx +++ b/docs/authentication/social-connections/microsoft.mdx @@ -94,7 +94,8 @@ To make the setup process easier, it's recommended to keep two browser tabs open 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. 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. 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` From 3f85ec4fb0d2fb52fe4c00d72647d2c9096ab248 Mon Sep 17 00:00:00 2001 From: vi Date: Tue, 8 Oct 2024 23:11:57 +0200 Subject: [PATCH 21/27] refactor --- .../social-connections/microsoft.mdx | 99 ++++++++++--------- 1 file changed, 50 insertions(+), 49 deletions(-) diff --git a/docs/authentication/social-connections/microsoft.mdx b/docs/authentication/social-connections/microsoft.mdx index 97e83a68e5..9106d0c683 100644 --- a/docs/authentication/social-connections/microsoft.mdx +++ b/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. --- - 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). -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: ### 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. ## 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. From 85ae2a3b95d298e43957c1b690bc36c7962ae943 Mon Sep 17 00:00:00 2001 From: vi Date: Tue, 8 Oct 2024 23:41:34 +0200 Subject: [PATCH 22/27] fix --- .../social-connections/microsoft.mdx | 74 +++++++++---------- 1 file changed, 37 insertions(+), 37 deletions(-) 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. From 949b64267be6aac8a89d7c237652bb6c8d1c872d Mon Sep 17 00:00:00 2001 From: victoria Date: Wed, 9 Oct 2024 12:44:08 +0200 Subject: [PATCH 23/27] Update docs/authentication/social-connections/microsoft.mdx Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> --- docs/authentication/social-connections/microsoft.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/authentication/social-connections/microsoft.mdx b/docs/authentication/social-connections/microsoft.mdx index 2f10208a3c..78fbb87f4d 100644 --- a/docs/authentication/social-connections/microsoft.mdx +++ b/docs/authentication/social-connections/microsoft.mdx @@ -32,8 +32,6 @@ 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 From 70e0577cae8656c4090c749f4dc0eaff634a2f9d Mon Sep 17 00:00:00 2001 From: victoria Date: Wed, 9 Oct 2024 12:44:15 +0200 Subject: [PATCH 24/27] Update docs/authentication/social-connections/microsoft.mdx Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> --- docs/authentication/social-connections/microsoft.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/social-connections/microsoft.mdx b/docs/authentication/social-connections/microsoft.mdx index 78fbb87f4d..b08172b41a 100644 --- a/docs/authentication/social-connections/microsoft.mdx +++ b/docs/authentication/social-connections/microsoft.mdx @@ -47,7 +47,7 @@ To configure your production instance, follow these steps: > 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, under **Manage**, select **[App registrations](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps)**. + 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. From 8dd4d8e066a6a65b7d02427422120835bd4b7f54 Mon Sep 17 00:00:00 2001 From: victoria Date: Wed, 9 Oct 2024 12:50:10 +0200 Subject: [PATCH 25/27] Update docs/authentication/social-connections/microsoft.mdx Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> --- docs/authentication/social-connections/microsoft.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/social-connections/microsoft.mdx b/docs/authentication/social-connections/microsoft.mdx index b08172b41a..cd892d7329 100644 --- a/docs/authentication/social-connections/microsoft.mdx +++ b/docs/authentication/social-connections/microsoft.mdx @@ -82,7 +82,7 @@ To configure your production instance, follow these steps: To connect your Clerk app to your Microsoft app, set the **Authorized redirect URI** in your Microsoft Azure portal. 1. Navigate back to the Microsoft Azure portal. - 1. In the sidebar, under **Manage**, select **Authentication**. + 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 earlier. From 28c00e52c054807265252fd06d98b762db5b6189 Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Wed, 9 Oct 2024 10:26:41 -0400 Subject: [PATCH 26/27] Update docs/authentication/social-connections/microsoft.mdx --- docs/authentication/social-connections/microsoft.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/social-connections/microsoft.mdx b/docs/authentication/social-connections/microsoft.mdx index cd892d7329..a110a38683 100644 --- a/docs/authentication/social-connections/microsoft.mdx +++ b/docs/authentication/social-connections/microsoft.mdx @@ -74,7 +74,7 @@ To configure your production instance, follow these steps: 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. - - Copy the **Authorized redirect URI**. You'll need it for the final step to configure your Entra ID app. + - Save the **Authorized redirect URI** somewhere secure. - Select **Add connection**. ### Enable OpenID From 9e51578a9e971a4ac75880350704715e1b1911c9 Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Wed, 9 Oct 2024 10:26:49 -0400 Subject: [PATCH 27/27] Update docs/authentication/social-connections/microsoft.mdx --- docs/authentication/social-connections/microsoft.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/social-connections/microsoft.mdx b/docs/authentication/social-connections/microsoft.mdx index a110a38683..1c83e2ddff 100644 --- a/docs/authentication/social-connections/microsoft.mdx +++ b/docs/authentication/social-connections/microsoft.mdx @@ -85,7 +85,7 @@ To configure your production instance, follow these steps: 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 earlier. + 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.