Clerk logo

Clerk Docs

Ctrl + K
Go to clerk.devGet API keys

Social Login (OAuth)

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

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.

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

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.

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

Configuration

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

Configure social login

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.

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

For development instances, Clerk will issue you a domain on "lcl.dev". In production, you'll need to supply your own domain. See Production setup or more information

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();

Read our detailed Clerk Hosted Pages guide to learn more.

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

👉 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.

Pre-built Clerk <SignUp/> component with Google social login, mounted in a NextJS app

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 InstancePaths. 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.

Was this helpful?

Clerk © 2022