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 16 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
95 changes: 41 additions & 54 deletions docs/authentication/social-connections/microsoft.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -21,75 +21,73 @@ 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).
</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 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 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. 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**.
victoriaxyz marked this conversation as resolved.
Show resolved Hide resolved
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).

<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) 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.
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**.
victoriaxyz marked this conversation as resolved.
Show resolved Hide resolved
> [!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.
victoriaxyz marked this conversation as resolved.
Show resolved Hide resolved

### 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**.
victoriaxyz marked this conversation as resolved.
Show resolved Hide resolved
1. Select the **Add connection** button, and select **For all users**.
victoriaxyz marked this conversation as resolved.
Show resolved Hide resolved
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 the Microsoft Azure portal.
- Copy the **Authorized redirect URI**. You need it for the final step to configure your Entra ID app.
alexisintech marked this conversation as resolved.
Show resolved Hide resolved
- 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 Entra ID app, you must 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. 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
Expand All @@ -100,50 +98,39 @@ To configure your production instance, follow these steps:
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.
victoriaxyz marked this conversation as resolved.
Show resolved Hide resolved

### 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 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.
</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 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.

## 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 are using [SAML with Microsoft](/docs/authentication/saml/azure), different tenant types _are_ supported and you can disregard these limitations.
Loading