Search…
Multi-factor authentication
Learn how to require a second step during authentication.

Overview

Clerk supports multi-factor authentication (MFA), often referred as two-factor authentication or 2FA. By enabling MFA, you can encourage or require your users to perform a second verification check during sign in.
The term multi-factor comes from the 3 main types of verifications:
  • Knowledge based - something you know, i.e. a password
  • Possession based - something you have, i.e. a phone or yubikey
  • Inherent based - something you are, i.e. a fingerprint or a facial scan
By enforcing two different types of verifications, you can drastically improve your users security. Most websites make this step optional, empowering their users with their own security.
Interested in single-factor authentication? Check out our guides on password-based and passwordless authentication.

Before you start

Configuration

There's two parts to enabling multi-factor authentication for your application. First, you need to apply the appropriate configuration setting in the Clerk Dashboard. Then, registered users need to turn on MFA for their own account through their User Profile page.

Dashboard configuration

From your dashboard, select your application and instance and then go to Settings > User Management > 2-step verification. We currently only support a second factor through an SMS code. However, we're constantly working on new features.
If you're interested in a specific 2FA method that we don't support yet, let us know!
Enabling SMS based MFA from your instance settings.
Don't forget to click on the Apply Changes button at the bottom of the page once you're done.

User profile configuration

Registered users will still need to enable MFA from their user profile page. Currently, MFA can not be required on all user accounts, this is coming soon.
Users will need to navigate to their user profile, and go to Security > Sign in > 2-step verification. From there, they will need to provide a phone number if there's not one on their account, and then enable it for that phone number.
Turning MFA on from your user profile.
Next, let's see how you can actually add multi-factor authentication to your application. The easiest ways are to use Clerk Hosted Pages or Clerk Components. If you want more flexibility, you can implement a custom multi-factor authentication flow for your application.

Using Clerk Hosted Pages

If you're looking for the fastest way to implement passwordless 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.
Getting the Clerk Hosted Pages URLs from the Clerk Dashboard.
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

You can leverage Clerk Components to easily add multi-factor authentication support to your application.
Clerk provides a <SignIn /> pre-built component that renders a sign in form and takes care of authenticating users and creating a session.
Note that you don't need to pass any special options to the pre-built <SignIn /> component. Multi-factor authentication will just work once users enable it under their profile settings, since it's already been configured through the Clerk Dashboard.
Clerk React
ClerkJS
1
import { SignIn } from "@clerk/clerk-react";
2
3
// SignInPage is your custom sign in page component.
4
function SignInPage() {
5
return (
6
// The Clerk SignIn component needs no special
7
// configuration.
8
<SignIn />
9
);
10
}
Copied!
1
<html>
2
<body>
3
<div id="sign-in"></div>
4
5
<script>
6
// Mount the pre-built Clerk SignIn component
7
// in an HTMLElement on your page.
8
const el = document.getElementById("sign-in");
9
window.Clerk.mountSignIn(el);
10
11
// Render the SignIn component as a
12
// modal on the page.
13
window.Clerk.openSignIn();
14
</script>
15
</body>
Copied!
If you're interested in more pre-built offerings, you can read more about Clerk Components.

Custom flow

In case one of the above integration methods doesn't cover your needs, you can make use of lower level commands and create a completely custom multi-factor authentication flow.
You still need to configure your instance in order to enable multi-factor authentication, as described in the Dashboard configuration section of this guide. Your users will also need to explicitly enable MFA for their account, as described in the User profile configuration section of this guide.
Signing in to an MFA enabled account is identical to the regular sign in process, however, a sign in won't convert until both verifications are completed.
The first three steps are part of the standard sign in flow. Steps 4 and 5 power are the additional authentication factor.
  1. 1.
    Initiate the sign-in process, by collecting the user's authentication identifier.
  2. 2.
    Prepare the first factor verification.
  3. 3.
    Attempt to complete the first factor verification.
  4. 4.
    Prepare the second factor verification. (This is where MFA comes into play)
  5. 5.
    Attempt to complete the second factor verification.
Let's see the above in action.
Clerk React
ClerkJS
1
import { useSignIn } from "@clerk/clerk-react";
2
3
function SignInPage() {
4
const signIn = useSignIn();
5
6
async function onClick(e) {
7
e.preventDefault();
8
// Sign the user in with email address and
9
// password.
10
await signIn.create({
11
identifier: "[email protected]",
12
password: "********",
13
});
14
15
// Prepare the second factor verification by
16
// specifying the phone code strategy. An SMS
17
// message with a one-time code will be sent
18
// to the user's verified phone number.
19
await signIn.prepareSecondFactor({
20
strategy: "phone_code",
21
});
22
23
// Attempt to complete the second factor
24
// verification, passing the previously
25
// received one-time code.
26
await signIn.attemptSecondFactor({
27
strategy: "phone_code",
28
code: "123456",
29
});
30
}
31
32
return (
33
<button onClick={onClick}>
34
Sign in with MFA
35
</button>
36
);
37
}
Copied!
1
const { client } = window.Clerk;
2
3
// Sign the user in with the required first
4
// factor strategy. In this case it's email
5
// and password.
6
const signIn = await client.signIn.create({
7
identifier: "[email protected]",
8
password: "**********",
9
});
10
11
// Prepare the second factor verification by
12
// specifying the phone code strategy. An SMS
13
// message with a one-time code will be sent
14
// to the user's verified phone number.
15
await signIn.prepareSecondFactor({
16
strategy: "phone_code",
17
});
18
19
// Attempt to complete the second factor
20
// verification, passing the previously
21
// received one-time code.
22
await signIn.attemptSecondFactor({
23
strategy: "phone_code",
24
code: "123456",
25
});
Copied!
You can learn more details about sign-ins by reading our Sign in flow documentation.
Last modified 1mo ago