Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 32 commits into from
Oct 9, 2024
Merged
Changes from all commits
Commits
Show all changes
32 commits
Select commit Hold shift + click to select a range
4972ccc
ff
victoriaxyz Oct 7, 2024
792817f
Update docs/authentication/social-connections/microsoft.mdx
victoriaxyz Oct 8, 2024
7455ed5
Update docs/authentication/social-connections/microsoft.mdx
victoriaxyz Oct 8, 2024
b0a0460
Update docs/authentication/social-connections/microsoft.mdx
victoriaxyz Oct 8, 2024
b912c25
Update docs/authentication/social-connections/microsoft.mdx
victoriaxyz Oct 8, 2024
d72fe5f
Update docs/authentication/social-connections/microsoft.mdx
victoriaxyz Oct 8, 2024
cedfcb8
Update docs/authentication/social-connections/microsoft.mdx
victoriaxyz Oct 8, 2024
d74c753
Update docs/authentication/social-connections/microsoft.mdx
victoriaxyz Oct 8, 2024
e38f502
Update docs/authentication/social-connections/microsoft.mdx
victoriaxyz Oct 8, 2024
4968fba
Update docs/authentication/social-connections/microsoft.mdx
victoriaxyz Oct 8, 2024
fba3e90
Update docs/authentication/social-connections/microsoft.mdx
victoriaxyz Oct 8, 2024
2d5cbb1
Update docs/authentication/social-connections/microsoft.mdx
victoriaxyz Oct 8, 2024
f612501
Update docs/authentication/social-connections/microsoft.mdx
victoriaxyz Oct 8, 2024
714c4d6
fix
victoriaxyz Oct 8, 2024
38acb59
Merge branch 'main' into vi/ff/oauth-microsoft
victoriaxyz Oct 8, 2024
94232f6
remove next steps
victoriaxyz Oct 8, 2024
41e77ee
Update docs/authentication/social-connections/microsoft.mdx
victoriaxyz Oct 8, 2024
1115aa4
Update docs/authentication/social-connections/microsoft.mdx
victoriaxyz Oct 8, 2024
e8884a2
Update docs/authentication/social-connections/microsoft.mdx
victoriaxyz Oct 8, 2024
baf7799
Update docs/authentication/social-connections/microsoft.mdx
victoriaxyz Oct 8, 2024
a68f5c5
Merge branch 'main' into vi/ff/oauth-microsoft
victoriaxyz Oct 8, 2024
0c9a296
update test oauth steps
victoriaxyz Oct 8, 2024
3f85ec4
refactor
victoriaxyz Oct 8, 2024
85ae2a3
fix
victoriaxyz Oct 8, 2024
7d0d3a1
Merge branch 'main' into vi/ff/oauth-microsoft
victoriaxyz Oct 8, 2024
949b642
Update docs/authentication/social-connections/microsoft.mdx
victoriaxyz Oct 9, 2024
70e0577
Update docs/authentication/social-connections/microsoft.mdx
victoriaxyz Oct 9, 2024
1dc2f3d
Merge branch 'main' into vi/ff/oauth-microsoft
victoriaxyz Oct 9, 2024
8dd4d8e
Update docs/authentication/social-connections/microsoft.mdx
victoriaxyz Oct 9, 2024
7b0b151
Merge branch 'main' into vi/ff/oauth-microsoft
victoriaxyz Oct 9, 2024
28c00e5
Update docs/authentication/social-connections/microsoft.mdx
alexisintech Oct 9, 2024
9e51578
Update docs/authentication/social-connections/microsoft.mdx
alexisintech Oct 9, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
115 changes: 51 additions & 64 deletions docs/authentication/social-connections/microsoft.mdx
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
---
title: Add Microsoft Azure Entra ID as a social connection
description: Learn how to allow users to sign into your Clerk app with their Microsoft account using OAuth.
description: Learn how to allow users to sign up and sign in to your Clerk app with their Microsoft account using OAuth.
---

<TutorialHero
beforeYouStart={[
{
title: "A Clerk application is required.",
title: "A Clerk app is required.",
link: "/docs/quickstarts/setup-clerk",
icon: "clerk",
},
Expand All @@ -18,132 +18,119 @@ description: Learn how to allow users to sign into your Clerk app with their Mic
]}
>
- Use Microsoft Azure Entra ID to authenticate users with OAuth.
- Protect your application from [the nOAuth exploit](https://www.descope.com/blog/post/noauth).
- Protect your app from [the nOAuth exploit](https://www.descope.com/blog/post/noauth).
</TutorialHero>

Enabling OAuth with Microsoft Azure Entra ID (formerly [Active Directory](https://learn.microsoft.com/en-us/entra/fundamentals/new-name)) allows your users to sign in and sign up to your Clerk application with their Microsoft account.
Enabling OAuth with Microsoft Azure Entra ID (formerly [Active Directory](https://learn.microsoft.com/en-us/entra/fundamentals/new-name)) allows your users to sign up and sign in to your Clerk app with their Microsoft account.

## Configure for your development instance

For _development instances_, Clerk uses preconfigured shared OAuth credentials and redirect URIsno other configuration is needed.
For _development instances_, Clerk uses preconfigured shared OAuth credentials and redirect URIsno other configuration is needed.

To configure your development instance, follow these steps:

1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections).
1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**.
1. Select the **Add connection** button, and select **For all users**.
1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page.
1. Select **Add connection** and select **For all users**.
1. In the **Choose provider** dropdown, select **Microsoft**.
1. Select **Add connection**.

## Configure for your production instance

In _production instances_, you must provide custom credentials, which involves generating your own **Client ID** and **Client Secret** using your Microsoft Entra ID dashboard account.
In _production instances_, you must provide custom credentials, which involves generating your own **Client ID** and **Client Secret** using your Microsoft Entra ID account.

To configure your production instance, follow these steps:

<Steps>
### Create a Microsoft Entra ID app

> [!TIP]
> If you already have a Microsoft Entra ID app you'd like to connect to Clerk, select your app from the [Microsoft Entra ID dashboard](https://portal.azure.com/#home) and skip to [the next step in this tutorial](#get-your-client-id-and-client-secret).
> If you already have a Microsoft Entra ID app you'd like to connect to Clerk, select your app from the [Microsoft Azure portal](https://portal.azure.com/#home) and skip to [the next step in this tutorial](#get-your-client-id-and-client-secret).

1. On the homepage of [the Azure portal](https://portal.azure.com/#home), in the **Azure services** section, select **[Microsoft Entra ID](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/Overview)**.
1. In the sidebar, under **Manage**, select **[App registrations](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps)**.
1. Select **New Registration**. You'll be taken to the **Register an application** page.
1. Fill out the form as follows:
1. Under **Name**, name the app whatever you'd like. "Clerk Demo App", for example.
1. On the homepage of the [Microsoft Azure portal](https://portal.azure.com/#home), in the **Azure services** section, select **[Microsoft Entra ID](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/Overview)**.
1. In the sidebar, open the **Manage** dropdown and select **[App registrations](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps)**.
1. Select **New Registration**. You'll be redirected to the **Register an application** page.
1. Complete the form as follows:
1. Under **Name**, name your app.
1. Under **Supported account types**, select **Accounts in any organizational directory (Any Microsoft Entra ID tenant – Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)**.
1. Under **Redirect URI (Optional)**, select **Web**.
1. Finally, select **Register** to submit the form.
1. Select **Register** to submit the form.

### Get your client ID and client secret

Once your Microsoft Entra ID app is created, or once you select your app from the Microsoft Entra ID dashboard, you'll be taken to its **Overview**.
Once your Microsoft Entra ID app is created, or once you select your app from the Microsoft Azure portal, you'll be redirected to its **Overview**.

1. From your app's overview, copy the **Application (client) ID** and save it somewhere secure. It's required for connecting your Microsoft Entra ID app to your Clerk app.
1. On this same page, under **Client credentials**, select **Add a certificate or secret** to generate a Client Secret. You'll be taken to the **Certificate & secrets** page.
1. Select the **New client secret** button. In the modal that opens, add a description and set an expiration time for your secret.
1. From your app's overview, copy the **Application (client) ID** and save it securely. You'll need it to connect your Microsoft Entra ID app to your Clerk app.
1. Under **Client credentials**, select **Add a certificate or secret** to generate a Client Secret. You'll be redirected to the **Certificate & secrets** page.
1. Select **New client secret**. In the modal that opens, add a description and set an expiration time for your secret.
> [!IMPORTANT]
> When your secret expires, your social connection will stop working until you generate a new client secret and add it to your Clerk app.
1. Copy your new client secret's **Value** and save it somewhere secure. You'll add it to your Clerk application later, alongside your client ID.
1. Leave this tab open.
1. Copy your new client secret's **Value** and save it securely. You'll add this and your client ID to your Clerk app later. Keep this page open.

### Connect your Entra ID app and get your redirect URI
victoriaxyz marked this conversation as resolved.
Show resolved Hide resolved

1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections).
1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**.
1. Select the **Add connection** button, and select **For all users**.
1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page.
1. Select **Add connection** and select **For all users**.
1. In the **Choose provider** dropdown, select **Microsoft**.
1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. Then:
- Under **Client ID**, add the value you copied from **Application (client) ID** in the Microsoft Entra ID dashboard.
- Under **Client Secret**, add the client secret value you generated in the Microsoft Entra ID dashboard.
- Copy the **Authorized redirect URI**. You need it for the final step to configure your Entra ID app.
- Under **Client ID**, add the value you copied from **Application (client) ID** in the Microsoft Azure portal.
- Under **Client Secret**, add the client secret value you generated.
- Save the **Authorized redirect URI** somewhere secure.
- Select **Add connection**.

### Enable OpenID

To connect your Clerk app to your Microsoft app, you must set the **Authorized redirect URI** in your Microsoft Entra ID dashboard.
To connect your Clerk app to your Microsoft app, set the **Authorized redirect URI** in your Microsoft Azure portal.

1. Return to the tab where your Microsoft Entra ID dashboard is open.
1. In the sidebar, under **Manage**,select **Authentication**.
1. Navigate back to the Microsoft Azure portal.
1. In the sidebar, open the **Manage** dropdown and select **Authentication**.
1. Select **Add a platform**.
1. Select **Web**.
1. In the **Redirect URIs** field and the **Front-channel logout URL** field, add the **Authorized redirect URI** you copied in the previous step.
1. In the **Redirect URIs** field and the **Front-channel logout URL** field, add the **Authorized redirect URI** you copied from the Clerk Dashboard.
1. Under **Implicit grant and hybrid flows**, check both **Access tokens** and **ID tokens**.
1. Select **Configure** to save the changes.

### Test your OAuth

The simplest way to test your OAuth is to visit your Clerk application's [Account Portal](/docs/customization/account-portal/overview), which is available for all Clerk applications out-of-the-box.
The simplest way to test your OAuth is to visit your Clerk app's [Account Portal](/docs/customization/account-portal/overview), which is available for all Clerk apps out-of-the-box.

1. In the navigation sidebar of the Clerk Dashboard, select [**Account Portal**](https://dashboard.clerk.com/last-active?path=account-portal).
1. In the Clerk Dashboard, navigate to the [**Account Portal**](https://dashboard.clerk.com/last-active?path=account-portal) page.
1. Next to the **Sign-in** URL, select **Visit**. The URL should resemble:
- **For development** – `https://your-domain.accounts.dev/sign-in`
- **For production** – `https://accounts.your-domain.com/sign-in`
1. On the sign-in page, you should see **Microsoft** as an option. Use it to sign in with your Microsoft account.

- **For development** – `https://your-domain.accounts.dev/sign-in`
- **For production** – `https://accounts.your-domain.com/sign-in`

1. Sign in with your Microsoft account.

### Secure your app against the nOAuth vulnerability

[nOAuth](https://www.descope.com/blog/post/noauth) is an exploit in Microsoft Entra ID OAuth applications that can lead to full account takeovers via email address spoofing. To protect users, Clerk enforces stricter checks on verified email addresses.
[nOAuth](https://www.descope.com/blog/post/noauth) is an exploit in Microsoft Entra ID OAuth apps that can lead to account takeovers via email address spoofing. Clerk mitigates this risk by enforcing stricter checks on verified email addresses.

For further security, Microsoft has an optional `xms_edov` claim, which provides additional context to that can be used to determine whether the returned email is verified.
For further security, Microsoft offers an optional `xms_edov` claim, which provides additional context to determine whether the returned email is verified.

To enable this optional claim, you must:

1. Navigate to your Azure application in the Microsoft Entra ID dashboard.
1. In the Microsoft Azure portal, navigate to your app.
1. In the sidebar, select **Token configuration**.
1. Select **Add optional claim**.
1. For the **Token type**, select **ID**. Then, in the checklist that appears, enable the `email` and `xms_pdl` claims.
1. At the bottom of the modal, select the **Add** button. A modal will appear asking you to **Turn on the Microsoft Graph email permission**. Enable it, then select **Add** to complete the form.
1. For the **Token type**, select **ID**. Then, in the table that opens, enable the `email` and `xms_pdl` claims.
1. At the bottom of the modal, select **Add**. A new modal will prompt you to turn on the Microsoft Graph email permission. Enable it, then select Add to complete the form.
> [!NOTE]
> At the time of writing, the `xms_edov` claim is still in preview, and may not be available for all applications. So we'll choose another one from the list and we'll rename it later on in the manifest.
1. Repeat the previous steps, but for the **Token type**, select **Access** instead of **ID**. When you're done, the list of **Optional claims** on this page should have two claims for `email` and two for `xms_pdl`: one each for **ID** and **Access**.
> At the time of writing, the `xms_edov` claim is still in preview and may not be available for all apps. We'll choose another claim and rename it in the manifest later.
1. Repeat the previous steps for **Token type**, but select **Access** instead of **ID**. The **Optional claims** list should now show two claims for `email` and two for `xms_pdl`: one each for **ID** and **Access**.
1. In the sidebar, go to **Manifest**.
1. In the text editor, search for `"acceptMappedClaims"` and change its value from `null` to `true`.
1. Search for `"optionalClaims"` where you'll find the `idToken` and `accessToken` arrays. Each array has an object with the name `xms_pdl`. Change the name to `xms_edov`.
1. In the text editor, search for `"acceptMappedClaims"` and set its value from `null` to `true`.
1. Search for `"optionalClaims"`, where you'll find the `idToken` and `accessToken` arrays. Each array has an object with the name `xms_pdl`. Change the name to `xms_edov`.
1. At the top of the page, select **Save**.
1. In the sidebar, navigate back to **Token configuration** and confirm that the list of **Optional claims** includes two claims for `email` and two for `xms_edov`: one each for **ID** and **Access**.
1. In the sidebar, navigate back to **Token configuration** and confirm that the **Optional claims** list includes two claims for `email` and two for `xms_edov`: one each for **ID** and **Access**.

With these steps complete, Microsoft will send the `xms_edov` claim in the token, and Clerk will use it to determine whether the email is verified or not, even if it is used with Microsoft Entra ID.
With these steps complete, Microsoft will send the `xms_edov` claim in the token, which Clerk will use to determine whether the email is verified, even when used with Microsoft Entra ID.
</Steps>

## Limitations

- Currently Clerk supports only the `common` tenant type, which is intended for allowing sign-ins both from organization members and public Microsoft users.
- Selecting the desired tenant type (`common`, `organizations`, `consumers` or specific tenant ID) will become available in an upcoming version of Clerk.
- Only credentials of type `secret` are currently supported (not the `certificate` type).
- Currently, Clerk supports only the `common` tenant type, which allows sign-ins both from organization members and public Microsoft users.
- The option to selecting the desired tenant type (`common`, `organizations`, `consumers` or specific tenant ID) will be available in an upcoming version of Clerk.
- Only credentials of type `secret` are supported (not the `certificate` type).

> [!TIP]
> If you are using [SAML with Microsoft](/docs/authentication/saml/azure), the different tenant types _are_ supported and you can disregard these limitations.

## Next steps

<Cards>
- [SAML SSO with Microsoft Azure AD](/docs/authentication/saml/azure)
- Learn how to integrate Microsoft Azure AD with Clerk using SAML SSO.

---

- [Account Linking](/docs/authentication/social-connections/account-linking)
- Learn how Clerk handles account linking and manages unverified email addresses from social providers.
</Cards>
> If you're using [SAML with Microsoft](/docs/authentication/saml/azure), the different tenant types _are_ supported, and you can disregard these limitations.
Loading