Clerk logo

Clerk Docs

Ctrl + K
Go to clerk.devGet API keys

Multi-factor

Learn how to require a second step during authentication.

Overview

Clerk supports multifactor authentication (MFA), often referred to 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 user's 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 are 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 two types of second factors:

  1. SMS verification code
  2. Authenticator application (also known as TOTP - Time-based One-Time Password).

More second factor variants will be added in the future.

If you're interested in a specific Multi-factor method that we don't support yet, let us know!

multifactor-authentication

Don't forget to click on the Apply Changes button at the bottom of the page once you're done.

User profile configuration

After enabling the second factor of your preference, 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 can choose which second factor to enable, out of the factors that the admin has enabled in the dashboard.

The easiest ways to add multi-factor authentication to your application are to use Clerk Hosted Pages or Clerk Components.

Authenticator App (TOTP)

To be able to use this method with Clerk Hosted Account pages, you will need to opt in to version 4 (v4) of our components. This is enabled by default for new applications, but for existing apps you will need to navigate to Settings > General and enable New Clerk Components, as per the following screenshot:

New Clerk components setting
New Clerk components setting

Once this is on, users can visit User Profile > Security > 2-step Verification and enable Authenticator application.

The user will be presented with a QR code that they can scan with their preferred authenticator application such as Google Authenticator, 1Password, etc or if they prefer to do a manual setup they can copy the TOTP secret or URI to paste it in their app.

QR code for registering Clerk on an authenticator application
QR code for registering Clerk on an authenticator application

After performing the setup on their authenticator app, Clerk will prompt them for a code generated from the app so as to ensure that the configuration is correct and that they are indeed in possesion of an app with which they can authenticate to Clerk.

By providing a valid TOTP code, Authenticator App as a second factor will kick in after they authenticate with their first factor.

Prompt for TOTP code during sign-in
Prompt for TOTP code during sign-in

SMS verification code

If this method is available, the user can:

  • enable it on one of their existing phone numbers, or
  • add a new phone number on the fly and then select if for use as a second factor

security dashboard

Custom flow

If you want more flexibility, 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. Initiate the sign-in process, by collecting the user's authentication identifier.
  2. Prepare the first factor verification.
  3. Attempt to complete the first factor verification.
  4. Prepare the second factor verification. (This is where MFA comes into play)
  5. 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
});

Was this helpful?

Clerk © 2022