Social Connections (OAuth)
Clerk makes it easy to add social connection capabilities to your application. Social connections are designed to simplify the sign-up and sign-in process for the end-user, resulting in higher conversion rates, a streamlined user data collection flow, and an overall better user experience.
Social connections provide 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 Clerk's prebuilt components. If you prefer a more custom solution, check out how to build a completely custom social connection flow.
Before you start
- You need to create a Clerk Application in your Clerk Dashboard. For more information, check out the Set up your application guide.
- You need to install the correct SDK for your application. You can find steps on how to do so through Clerk's quickstart guides.
Configuration
For development instances, Clerk uses pre-configured shared OAuth credentials and redirect URIs to make the development flow as smooth as possible. This means that you can enable any provider without additional configuration. In the Clerk Dashboard, go to User & Authentication > Social Connections and toggle on the providers you want to use.
For production instances, you will need to configure the provider with your OAuth credentials. Don't worry, Clerk provides dedicated guides on how to do this for each provider.
Configure 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.
Request additional OAuth scopes after sign-up
With Clerk, you can request additional OAuth scopes even after a user has signed up.
For Clerk Components, this is handled automatically by Clerk. 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.
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.
Add Social Connection after sign-up
For each OAuth provider, you can choose whether it 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, a user can connect to further OAuth providers as well. There is no need to perform another sign-up.
When using Clerk's Account Portal pages, users can see which providers they have already connected to and which ones they can still connect to on their User Profile page.
If you are using Clerk's prebuilt components, you can use the <UserProfile/> component to allow users to connect to further OAuth providers.