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.

Sign up for GitHub

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

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

Merged
merged 2 commits into from
Oct 9, 2024
Merged

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

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0165bb5
ff: update microsoft oauth
victoriaxyz Oct 9, 2024
78456d8
Update docs/authentication/social-connections/microsoft.mdx
victoriaxyz 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
22 changes: 10 additions & 12 deletions docs/authentication/social-connections/microsoft.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,18 +27,16 @@ Enabling OAuth with Microsoft Azure Entra ID (formerly [Active Directory](https:

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. 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 account.
For _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
Expand All @@ -50,7 +48,7 @@ To configure your production instance, follow these steps:
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 **Name**, enter your app name.
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. Select **Register** to submit the form.
Expand All @@ -59,21 +57,21 @@ To configure your production instance, follow these steps:

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 securely. You'll need it to connect your Microsoft Entra ID app to your Clerk app.
1. From your app's overview, save the **Application (client) ID** somewhere secure. 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.
1. Select **New client secret**. In the modal that opens, enter 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 securely. You'll add this and your client ID to your Clerk app later. Keep this page open.
1. Save the new client secret's **Value** somewhere secure. 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. 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.
- Under **Client ID**, paste the value you copied from **Application (client) ID** in the Microsoft Azure portal.
- Under **Client Secret**, paste the client secret value you generated.
- Save the **Authorized redirect URI** somewhere secure.
- Select **Add connection**.

Expand All @@ -85,7 +83,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 from the Clerk Dashboard.
1. In the **Redirect URIs** field and the **Front-channel logout URL** field, paste 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.

Expand Down Expand Up @@ -113,7 +111,7 @@ To configure your production instance, follow these steps:
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 new modal will prompt 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 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**.
Expand Down
Loading