Social Connections (OAuth)

Clerk makes it easy to add social connection capabilities to your application. Social connections is designed to simplify the sign up and sign in processes for the end-user, resulting in higher conversion rates, a streamlined user data collection flow, and an overall better user experience.

Social connections provides better security than passwords and other long-lived knowledge-based secrets. With social connections, users gain frictionless access to your application by using their existing credentials from an OAuth provider (Google, Facebook, Twitter etc) without having to go through complicated registration flows.

The easiest way to add social connections is by using our prebuilt Clerk Components. If you prefer a more custom solution, check out how to build a completely custom social connection flow.

To enable a social connection provider, go to the Clerk Dashboard, select your Application,and navigate to User & Authentication➜ Social Connections. Social connection configuration consists of the following steps:

Clerk supports multiple providers, but for the purposes of this guide we will enable social connection with Google.

In development, after applying these changes, you're good to go! To make the development flow as smooth as possible, Clerk uses pre-configured shared OAuth credentials and redirect URIs. Navigate to your sign in or sign up page to see it in action 🙂

For production instances, you will need to create your own account with Google and generate your own Client ID and Client secret.

Finally, copy the Authorized redirect URI field and add it to the provider's app configuration dashboard. For more details, check out the following guides:

For each provider, there is a set of pre-configured OAuth scopes that are absolutely necessary for authentication to work properly with Clerk. We call them base scopes.

On top of them, you can specify any additional scopes supported by the provider, by adding them to the "Scopes" field when configuring a custom profile.

With Clerk, you can request additional OAuth scopes, depending on your business needs, even after a user has signed up.

For Clerk Components, this is handled automatically by us. You only have to pass the additionalOAuthScopes prop in the <UserProfile/> component or the corresponding userProfileProp in the <UserButton /> component, with any additional OAuth scope you would like per provider.

Of course, you can achieve the same functionality implementing a custom flow, leveraging the corresponding methods of our SDKs

You can retrieve the OAuth access tokens of your users via the OAuth Access Token Wallet endpoint that's available in the Clerk Backend API.

Using these tokens, you can query the respective OAuth providers for additional data of your users.

For each OAuth provider, you can choose whether will be available during sign-up and sign-in, or if the connection should be made later.

This is especially useful for applications that prefer to connect third-parties after the fact. For example, a Github connection can be made after sign-up if an application wants to read repository data.

After sign-up, Connections can be made through our <UserProfile/> component, or with a custom flow.

When signed in, one can connect to further OAuth providers as well, there is no need to perform another sign-up.

When using Clerk hosted pages, on the /user/account/social-accounts path one can see which providers the user has already connected to and which ones they can still connect to.

In the example above we can see that the user has already connected their GitHub & Google accounts, while they can also connect their Discord & Facebook accounts if they wish to.

Clicking on an already connected acccount will take the user to a detailed view of said acccount, whereas clicking on an unconnected provider will initiate the connection process by redirecting to the provider for authentication.

After completing the connection (or after cancelling, should someone change their mind), the user will be taken back to the same page.

Note that when signing up using different OAuth providers Clerk can only associate the accounts to the same user if the verified email returned by the provider is the same.

When connecting to an OAuth provider from the User Profile page, Clerk knows this concerns the currently signed in user, so there is no requirement for the email the provider returns to match the email of the current user.

To further customize your sign up and sign in pages, you can use Clerk Components to easily add authentication anywhere. Doing so will let you add a custom background, modify CSS, and much more. In fact, Clerk's own sign up and sign in pages follow this approach.