Social connections (OAuth)

Clerk makes it easy to add social connection capabilities to your application. With social connections, users gain frictionless access to your application by using their existing credentials from a social provider (Google, Facebook, X/Twitter, etc.) without having to go through complicated registration flows. 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.

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.

Enable a social connection

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 most social providers without additional configuration.

To enable a social connection:

1. Navigate to the Clerk Dashboard.
2. In the top navigation, select Configure. Then in the sidebar, select SSO Connections.
3. Select the Add connection button, and select For all users.
4. In the Choose provider dropdown, select the provider you want to use.
5. Select Add connection.

For production instances, you will need to configure the provider with custom OAuth credentials. See the social provider's dedicated guide for more information.

Configure additional OAuth scopes

Each OAuth provider requires a specific set of scopes that are necessary for proper authentication with Clerk. These essential scopes are pre-configured and automatically included by Clerk. They typically include permissions for basic profile information and email access, which are fundamental for user authentication and account creation.

In addition to the core scopes, you can specify additional scopes supported by the provider. These scopes can be used to access additional user data from the provider.

To add additional OAuth scopes, when you are enabling a new social connection, enable Use custom credentials. The Scopes field will appear.

Request additional OAuth scopes after sign-up

Clerk allows you to request additional OAuth scopes even after a user has signed up.

Pass the additionalOAuthScopes prop to the <UserProfile/> or <UserButton /> component, with any additional OAuth scope you would like per provider. The user will be prompted to reconnect their account in their user profile page.

Use the following tabs to see how to add additional OAuth scopes to the <UserProfile/> and <UserButton/> components.

<UserProfile
  additionalOAuthScopes={{
    google: ['foo', 'bar'],
    github: ['qux'],
  }}
/>

<UserButton
  userProfileProps={{
    additionalOAuthScopes: {
      google: ['foo', 'bar'],
      github: ['qux'],
    },
  }}
/>

Get an OAuth access token for a social provider

You can use a social provider's OAuth access token to access user data from that provider in addition to their data from Clerk.

To retrieve the OAuth access token for a user, use the getUserOauthAccessToken() method from the JavaScript Backend SDK. This method must be used in a server environment, and cannot be run on the client.

Clerk ensures that the OAuth access token will be always fresh so that you don't have to worry about refresh tokens.

The following example demonstrates how to retrieve the OAuth access token for a user and use it to fetch user data from the Notion API. It assumes:

• You have already enabled the Notion social connection in the Clerk Dashboard.
• The user has already connected their Notion account to your application.
• The user has the correct permissions to access the Notion API.

The example is written for Next.js App Router, but is supported by any React meta framework, such as Remix.

import { auth, clerkClient } from '@clerk/nextjs/server'
import { NextResponse } from 'next/server'

export async function GET() {
  const { userId } = auth()

  if (!userId) {
    return NextResponse.json({ message: 'User not found' })
  }

  // Get the OAuth access token for the user
  const provider = 'oauth_notion'

  const clerkResponse = await clerkClient().users.getUserOauthAccessToken(userId, provider)

  const accessToken = clerkResponse[0].token || ''

  if (!accessToken) {
    return NextResponse.json({ message: 'Access token not found' }, { status: 401 })
  }

  // Fetch the user data from the Notion API
  // This endpoint fetches a list of users
  // https://developers.notion.com/reference/get-users
  const notionUrl = 'https://api.notion.com/v1/users'

  const notionResponse = await fetch(notionUrl, {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Notion-Version': '2022-06-28',
    },
  })

  // Handle the response from the Notion API
  const notionData = await notionResponse.json()

  return NextResponse.json({ message: notionData })
}

Add a social connection after sign-up

For each social provider, you can disable the option to sign up and sign in to your application using the provider. This is especially useful for users that want to connect their OAuth account after authentication.

For example, say your application wants to read a user's GitHub repository data but doesn't want to allow the user to authenticate with their GitHub account. The user can sign up with their email and password, or whatever method you choose, and then afterwards, connect their GitHub account to your application.

After sign-up, connections can be made through Clerk's <UserProfile/> component, or with a custom flow.

To configure the option for users to sign up and sign in with a social provider:

1. Navigate to the Clerk Dashboard.
2. In the top navigation, select Configure. Then in the sidebar, select SSO Connections.
3. Select the social provider you want to configure.
4. Enable or disable Enable for sign-up and sign-in.
5. Save the changes.

Connecting to social providers while signed in

When signed in, a user can connect to further social providers. 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.

When using Clerk's prebuilt components, you can use the <UserProfile/> component to allow users to connect to further social providers.

OAuth for native applications

Currently, Clerk's prebuilt components are not supported in native applications, but you can use the Clerk API to build a custom flow for authenticating with social connections.

Clerk ensures that security critical nonces are passed only to allowlisted URLs when the OAuth flow is completed in native browsers or webviews. For maximum security in your production instances, you need to allowlist your custom redirect URLs via the Clerk Dashboard or the Clerk Backend API.

To allowlist a redirect URL via the Clerk Dashboard:

1. Navigate to the Clerk Dashboard.
2. In the top navigation, select Configure. Then in the sidebar, select SSO Connections.
3. Scroll to the Allowlist for mobile OAuth redirect section and add your redirect URLs.

OAuth for Apple native applications

You can use Sign in with Apple to offer a native authentication experience in your iOS, watchOS, macOS or tvOS apps.

Instead of the typical OAuth flow that performs redirects in a browser context, you can utilize Apple's native authorization and provide the openID token and grant code to Clerk. Clerk ensures that the user will be verified in a secure and reliable way with the information that Apple has provided about the user.

See the dedicated guide for additional information on how to configure Apple as a social provider for your Clerk instance.