Clerk logo

Clerk Docs

Ctrl + K
Go to clerk.dev

Social Connections (OAuth)

Learn how to effortlessly add social connections to your application using popular OAuth providers like Google, Facebook, Github and more.

Overview

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.

Pre-built Clerk <SignIn/> component with Facebook and Google social login.Pre-built Clerk <SignIn/> component with Facebook and Google social login.Pre-built Clerk <SignIn/> component with Facebook and Google social login.Pre-built Clerk <SignIn/> component with Facebook and Google social login.Pre-built Clerk <SignIn/> component with Facebook and Google social login.Pre-built Clerk <SignIn/> component with Facebook and Google social login.

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.

When using social connections, the sign up and sign in flows are equivalent. If a user doesn't have an account and tries to sign in, an account will be made for them, and vice versa.

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

Before you start

Configuration

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:

  1. Enable the providers you want to use.
  2. (production instances only) Enter your OAuth credentials (Client ID and Client Secret) for each provider
  3. (production instances only) Copy the Authorized redirect URI from the Clerk Dashboard to the provider's app configuration.

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

Configure Social Connection

We are constantly adding more providers. If you're interested in a provider we don't support yet, let us know!

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 πŸ™‚

Shared OAuth credentials should not be treated as secure. For this reason, we don't allow them in production.

Configuring Google SSO with a custom profile

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:

Configuring additional OAuth scopes

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.

OAuth Access Token Wallet

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.

Clerk ensures that the OAuth Access Token will be always fresh so that you don't have to worry about OAuth Refresh Tokens anymore.

Using Clerk Hosted Pages

If you're looking for the fastest way to implement social connections based authentication, you can leverage Clerk Hosted Pages for your sign up, sign in, and user profile pages. You can set these up on your own domain, and match your websites theme with the Clerk Dashboard to create a seamless experience.

Read our detailed Clerk Hosted Pages guide to learn more.

Add Social Connection after Sign Up

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.

Connecting to OAuth providers while signed in

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.

Social accounts section of User Profile

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.

Using Clerk Components

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.

Custom flow

In case one of the above integration methods doesn't cover your needs, you can leverage the Clerk SDK to build completely custom OAuth flows.

You still need to configure your instance through the Clerk Dashboard, as described at the top of this guide.

When using OAuth, the sign in and sign up are equivalent. A successful OAuth flow consists of the following steps:

  1. Start the OAuth flow by calling SignIn.authenticateWithRedirect(params) or SignUp.authenticateWithRedirect(params). Note that both of these methods require a redirectUrl param, which is the URL that the browser will be redirected to once the user authenticates with the OAuth provider.
  2. Create a route at the URL redirectUrl points, typically /sso-callback, that calls the Clerk.handleRedirectCallback() or simply renders the prebuilt <AuthenticateWithRedirectCallback/> component.

The React example below uses react-router-dom to define the required route. For NextJS apps, you only need to create a pages/sso-callback file.

1

To initiate an OAuth flow for a user that is already signed in, you can use the user.createExternalAccount(params) method, where user is a reference to the currently signed in user.

1

OAuth for Native applications

With Clerk you can add OAuth flows in your React-Native or Expo applications.

Clerk ensures that security critical nonces will be passed only to whitelisted URLs when the OAuth flow is complete in native browsers or webviews.

So for maximum security in your production instances, you need to whitelist your custom redirect URLs via Clerk Dashboard or Clerk Backend API.

Social login redirect URLs for native applications

Was this helpful?

Clerk Β© 2022