Social Login (OAuth)

Overview

Clerk makes it easy to add social login capabilities to your application. Social login 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 login provides better security than passwords and other long-lived knowledge-based secrets. With social login, 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 login 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 login flow.

Before you start

• You need to create a Clerk Application in your Clerk Dashboard. For more information, check out our Set up your application guide.
• You need to install Clerk React or ClerkJS to your application.

Configuration

To enable a social login provider, go to the Clerk Dashboard, select your Application,and navigate to User & Authentication➜ Social Login. Social login 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 login 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:

• ​How to setup social login with Google​
• ​How to setup social login with Facebook​
• ​How to setup social login with Twitter​
• ​How to setup social login with TikTok​
• ​How to setup social login with Discord​
• ​How to setup social login with Twitch​
• ​How to setup social login with Github​
• ​How to setup social login with GitLab​
• ​How to setup social login with LinkedIn​
• ​How to setup social login with Dropbox​
• ​How to setup social login with HubSpot​
• ​How to setup social login with Microsoft​
• ​How to setup social login with Notion​

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.

Using Clerk Hosted Pages

If you're looking for the fastest way to implement social login 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.

You can find your instances sign up and sign in links in the Home rsection of your instance in Clerk Dashboard.

By default, the URLs for your hosted pages will match the following pattern:

https://accounts.[your-domain].com/sign-in
https://accounts.[your-domain].com/sign-up
https://accounts.[your-domain].com/user

Clerk provides SDKs to make navigating to these pages easy.

1
import { 
2
    useClerk,
3
    RedirectToSignIn,
4
    RedirectToSignUp
5
} from "@clerk/clerk-react";
6

7
// Rendering the <RedirectToSignIn/> component will
8
// cause the browser to navigate to the Sign In URL
9
// and show the hosted Sign In page
10
function MyRedirectToSignIn() {
11
    return (
12
        <RedirectToSignIn/>
13
    )
14
}
15

16
// Rendering the <RedirectToSignUp/> component will
17
// cause the browser to navigate to the Sign Up URL
18
// and show the hosted Sign Up page
19
function MyRedirectToSignUp() {
20
    return (
21
        <RedirectToSignUp/>
22
    )
23
}
24

25
// You can also trigger a redirect programmatically 
26
// by calling the redirectToSignUp or redirectToSignIn
27
// methods 
28
function MyButtonRedirect() {
29
    const {redirectToSignUp, redirectToSignIn} = useClerk();
30

31
    return (
32
        <>
33
            <button onClick={redirectToSignUp}>
34
                Redirect to hosted Sign Up page
35
            </button>
36
            <button onClick={redirectToSignIn}>
37
                Redirect to hosted Sign In page
38
            </button>
39
        </>
40
    )
41
}
42

1
// Calling the redirectToSignUp method will
2
// cause the browser to navigate to the Sign In URL
3
// and show the hosted Sign Up page
4
window.Clerk.redirectToSignUp();
5

6
// Calling the redirectToSignIn method will
7
// cause the browser to navigate to the Sign In URL
8
// and show the hosted Sign In page
9
window.Clerk.redirectToSignIn();

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/connected-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.

Using Clerk Components

👉 Demo

👩‍💻 Example repo ​

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.

Clerk provides the <SignUp/> and <SignIn/> prebuilt components that render a conversion-optimized sign up and sign form.

Note that you don't need to pass any special props to the <SignUp/> and <SignIn/> components, it will automatically display the configuration you chose in the Clerk Dashboard.

When using social login, 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.

Showing a sign in form with social login is as simple as rendering the <SignIn/> component:

1
import { SignUp } from "@clerk/clerk-react";
2

3
// SignUpPage is your custom sign up page component
4
function SignUpPage() {
5
  return (
6
    <SignUp />
7
  );
8
}

1
<html>
2
<body>
3
    <div id="sign-in"></div>
4
    
5
    <script>
6
        const signInEl = document.getElementById("sign-in");
7
        // Mount the pre-built Clerk SignIn component
8
        // in an HTMLElement on your page. 
9
        window.Clerk.mountSignIn(signInEl);
10
        
11
        // Alternatively, you can open the SignIn 
12
        // component as a modal
13
        window.Clerk.openSignIn();
14
    </script>
15
</body>

In the same fashion, render the <SignUp/> component to show a sign up form with social login:

1
import { SignUp } from "@clerk/clerk-react";
2

3
// SignUpPage is your custom sign up page component
4
function SignUpPage() {
5
  return (
6
    <SignUp />
7
  );
8
}

1
<html>
2
<body>
3
    <div id="sign-in"></div>
4
    
5
    <script>
6
        const signInEl = document.getElementById("sign-in");
7
        // Mount the pre-built Clerk SignIn component
8
        // in an HTMLElement on your page. 
9
        window.Clerk.mountSignIn(signInEl);
10
        
11
        // Alternatively, you can open the SignIn 
12
        // component as a modal
13
        window.Clerk.openSignIn();
14
    </script>
15
</body>

And you're done! 🎉

To allow your users to connect to oauth providers after signing in, you can use the <ProfileCard /> component, which links to the <ConnectedAccountList /> component. The account list displays existing accounts & allows connecting to other providers as illustrated in the previous section.

The above examples don't require any specific routes to be defined, they automatically use the Clerk Hosted Pages to handle the required OAuth redirects. If you prefer having the mounted <SignIn/> and <SignUp/> components handle the OAuth redirects instead, you need to follow some additional steps:

From the Clerk Dashboard, select your Application, navigate to Instance ➜ Paths. Change the Sign Up URL to /sign-up and the Sign In URL to /sign-in.

Finally, in your app define a /sign-up route that renders the <SignUp /> component. Similarly, define a /sign-inroute that renders the <SignIn /> component as shown in the following example. Refer to the <SignIn/> and <SignUp/> docs to learn more about the routing and path props.

The React example below uses react-router-dom to define the routes. For more info, take a look at the example repo or consult the URLs & redirects docs.

1
import { SignUp, SignIn } from "@clerk/clerk-react";
2
import { Route, Switch, useHistory } from 'react-router-dom';
3

4
function App() {
5
  const { push } = useHistory();
6

7
  return (
8
    <ClerkProvider frontendApi={"[your-frontend-api]"} navigate={to => push(to)}>
9
      <Switch>
10
        <Route path='/sign-in'>
11
          <SignIn routing='path' path='/sign-in' />
12
        </Route>
13
        <Route path='/sign-up'>
14
          <SignUp routing='path' path='/sign-up' />
15
        </Route>
16
      </Switch>
17
    </ClerkProvider>
18
  );
19
}

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
import React from "react";
2
import {
3
  BrowserRouter,
4
  Switch,
5
  Route,
6
} from "react-router-dom";
7
import { OAuthStrategy } from "@clerk/types";
8
import {
9
  ClerkProvider,
10
  ClerkLoaded,
11
  AuthenticateWithRedirectCallback,
12
  UserButton,
13
  useSignIn,
14
} from "@clerk/clerk-react";
15

16
const frontendApi = process.env.REACT_APP_CLERK_FRONTEND_API;
17

18
function App() {
19
  return (
20
    //  react-router-dom requires your app to be wrapped with a Router
21
    <BrowserRouter>
22
      <ClerkProvider frontendApi={frontendApi}>
23
        <Switch>
24
          {/* Define a / route that displays the OAuth buttons */}
25
          <Route path="/">
26
            <SignedOut>
27
              <SignInOAuthButtons />
28
            </SignedOut>
29
            <SignedIn>
30
              <UserButton afterSignOutAllUrl="/" />
31
            </SignedIn>
32
          </Route>
33
         
34
           {/* Define a /sso-callback route that handle the OAuth redirect flow */}
35
          <Route path="/sso-callback">
36
            <SSOCallback />
37
          </Route>
38
        </Switch>
39
      </ClerkProvider>
40
    </BrowserRouter>
41
  );
42
}
43

44
function SSOCallback() {
45
  // Handle the redirect flow by rendering the
46
  // prebuilt AuthenticateWithRedirectCallback component.
47
  // This is the final step in the custom OAuth flow
48
  return <AuthenticateWithRedirectCallback />;
49
}
50

51
function SignInOAuthButtons() {
52
  const { signIn } = useSignIn();
53

54
  const signInWith = (strategy: OAuthStrategy) => {
55
    return signIn.authenticateWithRedirect({
56
      strategy,
57
      redirectUrl: "/sso-callback",
58
      redirectUrlComplete: "/",
59
    });
60
  };
61

62
  // Render a button for each supported OAuth provider
63
  // you want to add to your app
64
  return (
65
    <div>
66
      <button onClick={() => signInWith("oauth_google")}>
67
        Sign in with Google
68
      </button>
69
    </div>
70
  );
71
}
72

73
export default App;

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
user
2
      .createExternalAccount({ strategy: strategy, redirect_url: 'your-redirect-url' })
3
      .then(externalAccount => {
4
        // navigate to
5
        // externalAccount.verification!.externalVerificationRedirectURL
6
      })
7
      .catch(err => {
8
        // handle error
9
      });

Token Wallet

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

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