Multifactor auth (MFA)

Learn how to require a second step during authentication.

Overview

Clerk supports multifactor 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

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

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 Authentication > Multi-factor. 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 Multi-factor method that we don't support yet, let us know!

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.

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.

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
}

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.

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 t`o 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 on the Multi-factor authentication page.

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
}

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>

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.

Initiate the sign-in process, by collecting the user's authentication identifier.
Prepare the first factor verification.
Attempt to complete the first factor verification.
Prepare the second factor verification. (This is where MFA comes into play)
Attempt to complete the second factor verification.

Let's see the above in action.

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: "user@example.com",
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
}

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: "user@example.com",
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
});

You can learn more details about sign-ins by reading our Sign in flow documentation.