Search…
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
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 Instances ➜ Settings ➜ User Management ➜ SSO.
Social login configuration consists of the following steps:
  1. 1.
    Enable the providers you want to use.
  2. 2.
    (production instances only) Enter your OAuth credentials (Client ID and Client Secret) for each provider
  3. 3.
    (production instances only) Copy the Authorized redirect URI from the Clerk Dashboard to the provider's app configuration.
Enabling social login providers
Clerk supports the following providers: Facebook, Google, Github, HubSpot, TikTok, GitLab and Discord. For the purposes of this guide we will enable social login with Google.
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 preconfigured 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.
Entering the credentials for an OAuth provider
For production instances, you will need to create your own account with Google and generate your own Client ID and Client secret. You can add these by pressing the Manage credentials button under the respective provider. For more details, check out the following guides:
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:
Don't forget to click Apply Changes button at the bottom of the page once you're done.

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 > Instance configuration section of your instance in Clerk Dashboard.
Sign up and sign in links for Clerk Hosted Pages
By default, the URLs for your hosted pages will match the following pattern:
1
https://accounts.[your-domain].com/sign-in
2
https://accounts.[your-domain].com/sign-up
3
https://accounts.[your-domain].com/user
Copied!
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.
Clerk React
Clerk.js
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
​
Copied!
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();
Copied!
Read our detailed Clerk Hosted Pages guide to learn more.

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:
Clerk React
Clerk.js
1
import { SignUp } from "@clerk/clerk-react";
2
​
3
// SignInPage is your custom sign in page component
4
function SignInPage() {
5
return (
6
<SignIn />
7
);
8
}
Copied!
1
<html>
2
<body>
3
<div id="sign-up"></div>
4
5
<script>
6
const el = document.getElementById("sign-up");
7
// Mount the pre-built Clerk SignUp component
8
// in an HTMLElement on your page.
9
window.Clerk.mountSignUp(el);
10
11
// Alternatively, you can open the SignUp
12
// component as a modal
13
window.Clerk.openSignUp();
14
</script>
15
</body>
16
</html>
Copied!
In the same fashion, render the <SignUp/> component to show a sign up form with social login:
Clerk React
Clerk.js
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
}
Copied!
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>
Copied!
And you're done! πŸŽ‰
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 ➜ Settings ➜ URLs & redirects ➜ Component URLs. 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-domto define the routes. For more info, take a look at the example repo or consult the URLs & redirects docs.
Clerk React
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
}
Copied!

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. 1.
    Start the OAuth flow by calling SignIn.authenticateWithRedirect(params) or SignUp.authenticateWithRedirect(params). Note that both of these methods require a callbackUrl param, which is the URL that the browser will be redirected to once the user authenticates with the OAuth provider.
  2. 2.
    Create a route at the URL callbackUrl points, typically /sso-callback, that calls the Clerk.handleRedirectCallback() or simply renders the prebuilt <AuthenticateWithRedirectCallback/> component.
The React example below uses react-router-domto define the required route. For NextJS apps, you only need to create a pages/sso-callback file.
Clerk React
App.tsx
1
import React from "react";
2
import { OAuthStrategy } from "@clerk/types";
3
import {
4
ClerkProvider,
5
ClerkLoaded,
6
AuthenticateWithRedirectCallback,
7
UserButton,
8
useSignIn,
9
} from "@clerk/clerk-react";
10
​
11
const frontendApi = process.env.REACT_APP_CLERK_FRONTEND_API;
12
​
13
function App() {
14
return (
15
// react-router-dom requires your app to be wrapped with a Router
16
<BrowserRouter>
17
<ClerkProvider frontendApi={frontendApi}>
18
<Switch>
19
{/* Define a / route that displays the OAuth buttons */}
20
<Route path="/">
21
<SignedOut>
22
<SignInOAuthButtons />
23
</SignedOut>
24
<SignedIn>
25
<UserButton afterSignOutAllUrl="/" />
26
</SignedIn>
27
</Route>
28
29
{/* Define a /sso-callback route that handle the OAuth redirect flow */}
30
<Route path="/sso-callback">
31
<SSOCallback />
32
</Route>
33
</Switch>
34
</ClerkProvider>
35
</BrowserRouter>
36
);
37
}
38
​
39
function SSOCallback() {
40
// Handle the redirect flow by rendering the
41
// prebuilt AuthenticateWithRedirectCallback component.
42
// This is the final step in the custom OAuth flow
43
return <AuthenticateWithRedirectCallback />;
44
}
45
​
46
function SignInOAuthButtons() {
47
const { authenticateWithRedirect } = useSignIn();
48
​
49
const signInWith = (strategy: OAuthStrategy) => {
50
return authenticateWithRedirect({
51
strategy,
52
callbackUrl: "/sso-callback",
53
callbackUrlComplete: "/",
54
});
55
};
56
​
57
// Render a button for each supported OAuth provider
58
// you want to add to your app
59
return (
60
<div>
61
<button onClick={() => signInWith("oauth_google")}>
62
Sign in with Google
63
</button>
64
</div>
65
);
66
}
67
​
68
export default App;
Copied!
​
Last modified 10d ago