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

Update Microsoft OAuth guide; align copy about development vs production instances in other guides #1588

Merged
merged 20 commits into from
Oct 4, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
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
5 changes: 3 additions & 2 deletions docs/authentication/social-connections/apple.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,9 @@ Enabling OAuth via [Sign in with Apple](https://developer.apple.com/sign-in-with

## Configure for your development instance

To make the development flow as smooth as possible, Clerk uses preconfigured shared OAuth credentials and redirect URIs for _development instances_.
For **web based flows**, no other configuration is needed. For **native sign-in flows**, you must provide your app's [Bundle ID](https://developer.apple.com/documentation/appstoreconnectapi/bundle_ids).
For _development instances_, Clerk uses preconfigured shared OAuth credentials and redirect URIs. For **web based flows**, no other configuration is needed. For **native sign-in flows**, you must provide your app's [Bundle ID](https://developer.apple.com/documentation/appstoreconnectapi/bundle_ids).

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**.
Comment on lines 31 to 32
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should condense this from
In the top navigation, select Configure. Then in the sidebar, select SSO Connections.
to
In your Clerk Dashboard, go to User & Authentication > SSO Connections.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

but then an unknowing user will click every tab at the top, and search the entire page looking for "User & Authentication". until they reach the fourth and final tab.
so I don't agree with this - I think because we don't use screenshots, and because we now have four entirely separate contexts, we should be very explicit when directing the user to what context they should be looking at ("configure").

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's fair!

Expand Down
8 changes: 6 additions & 2 deletions docs/authentication/social-connections/huggingface.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,9 @@ Enabling OAuth with [Hugging Face](https://huggingface.co/) allows your users to

## Configure for your development instance

To make the development flow as smooth as possible, Clerk uses preconfigured shared OAuth credentials and redirect URIs for _development instances_ — 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. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**.
Expand All @@ -34,7 +36,9 @@ To make the development flow as smooth as possible, Clerk uses preconfigured sha

## Configure for your production instance

In _production instances_, you must provide custom credentials, which includes generating your own **Client ID** and **Client Secret** using your Hugging Face account. This tutorial will walk you through that process in just a few steps.
In _production instances_, you must provide custom credentials, which involves generating your own **Client ID** and **Client Secret** using your Hugging Face account.

To configure your production instance, follow these steps:

<Steps>
### Create a Hugging Face Connected App
Expand Down
8 changes: 6 additions & 2 deletions docs/authentication/social-connections/linkedin-oidc.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,9 @@ description: Learn how to allow users to sign into your Clerk app with their Lin

## Configure for your development instance

To make the development flow as smooth as possible, Clerk uses preconfigured shared OAuth credentials and redirect URIs for _development instances_ - 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. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**.
Expand All @@ -32,7 +34,9 @@ To make the development flow as smooth as possible, Clerk uses preconfigured sha

## Configure for your production instance

In _production instances_, you must provide custom credentials, which includes generating your own **Client ID** and **Client Secret** using your LinkedIn Developer account. Don't worry, this tutorial will walk you through that process in just a few steps.
In _production instances_, you must provide custom credentials, which involves generating your own **Client ID** and **Client Secret** using your LinkedIn Developer account.

To configure your production instance, follow these steps:

<Steps>
### Create a LinkedIn application
Expand Down
26 changes: 17 additions & 9 deletions docs/authentication/social-connections/microsoft.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,9 @@ Enabling OAuth with Microsoft Azure Entra ID (formerly [Active Directory](https:

## Configure for your development instance

To make the development flow as smooth as possible, Clerk uses preconfigured shared OAuth credentials and redirect URIs for _development instances_ - 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. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**.
Expand All @@ -35,16 +37,18 @@ To make the development flow as smooth as possible, Clerk uses preconfigured sha

## Configure for your production instance

In _production instances_, you must provide custom credentials, which includes generating your own **Client ID** and **Client Secret** using your Microsoft Entra ID dashboard account. Don't worry, this tutorial will walk you through that process in just a few steps.
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.

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).

1. Under the **Azure services** section on the homepage of [the Azure portal](https://portal.azure.com/#home), select **[Microsoft Entra ID](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/Overview)**.
1. In the sidebar, select **[App registrations](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps)**.
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.
Expand All @@ -56,12 +60,13 @@ In _production instances_, you must provide custom credentials, which includes g

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**.

1. From your app's overview, copy the **Application (client) ID** and save it somewhere secure. It's required connecting your Microsoft Entra ID app to your Clerk app.
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.
> [!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.

### Connect your Entra ID app and get your redirect URI

Expand All @@ -80,9 +85,12 @@ In _production instances_, you must provide custom credentials, which includes g
To connect your Clerk app to your Microsoft app, you must set the **Authorized redirect URI** in your Microsoft Entra ID dashboard.

1. Return to the tab where your Microsoft Entra ID dashboard is open.
1. In the sidebar, select **Authentication**, then select **Add a platform**.
1. Select **Single-page application**.
1. In the **Redirect URIs** field of the modal that appears, add your Clerk application's authorized redirect URI. Do the same in the **Front-channel logout URL** field.
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. Under **Implicit grant and hybrid flows**, check both **Access tokens** and **ID tokens**.
1. Select **Configure** to save the changes.

### Test your OAuth

Expand All @@ -92,7 +100,7 @@ In _production instances_, you must provide custom credentials, which includes g
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 **Continue with 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. Use it to sign in with your Microsoft account.

### Secure your app against the nOAuth vulnerability

Expand Down
2 changes: 1 addition & 1 deletion docs/authentication/social-connections/spotify.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Learn how to set up a social connection with Spotify in your Clerk application.

## Overview

**Clerk does not currently support preconfigured shared OAuth credentials for Spotify on development instances.** You will have to provide custom credentials for both development _and_ production instances, which includes generating your own Client ID and Client Secret using your Spotify Developer account. Don't worry, this guide will walk you through that process in just a few simple steps.
**Clerk does not currently support preconfigured shared OAuth credentials for Spotify on development instances.** You will have to provide custom credentials for both development _and_ production instances, which involves generating your own Client ID and Client Secret using your Spotify Developer account. Don't worry, this guide will walk you through that process in just a few simple steps.

> [!CAUTION]
> [Spotify](https://developer.spotify.com/documentation/web-api/concepts/quota-modes) requires users to be added to the Spotify application's allowlist in order to allow them to connect to your Clerk application with Spotify OAuth. Each user who attempts to use your Clerk app in **development** with Spotify as their authentication method will need to be added to your app's allowlist before they can use it. _Your users may be able to log into your development Clerk app without having been allowlisted in Spotify. However, API requests with an access token associated to that user and Spotify app will receive a 403 status code error._
Expand Down
2 changes: 1 addition & 1 deletion docs/authentication/social-connections/x-twitter.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ description: Learn how to set up a social connection with X/Twitter v2 in your C

## Overview

Clerk does not currently support preconfigured shared OAuth credentials for X/Twitter on development instances. This means you will have to provide custom credentials for both development _and_ production instances, which includes generating your own **Client ID** and **Client Secret** using your X/Twitter Developer account. This tutorial will walk you through that process in just a few simple steps.
Clerk does not currently support preconfigured shared OAuth credentials for X/Twitter on development instances. This means you will have to provide custom credentials for both development _and_ production instances, which involves generating your own **Client ID** and **Client Secret** using your X/Twitter Developer account. This tutorial will walk you through that process in just a few simple steps.

> [!WARNING]
> X/Twitter v2 is currently not providing email addresses of users. The user will have to fill in their email address manually when they return to your application after authenticating with X/Twitter.
Expand Down
Loading