Two-Factor Authentication (2FA)

OTP TOTP Backup Codes Trusted Devices

Two-Factor Authentication (2FA) adds an extra security step when users log in. Instead of just using a password, they'll need to provide a second form of verification. This makes it much harder for unauthorized people to access accounts, even if they've somehow gotten the password.

This plugin offers two main methods to do a second factor verification:

1. OTP (One-Time Password): A temporary code sent to the user's email or phone.
2. TOTP (Time-based One-Time Password): A code generated by an app on the user's device.

Additional features include:

• Generating backup codes for account recovery
• Enabling/disabling 2FA
• Managing trusted devices

Installation

import { betterAuth } from "better-auth"
import { twoFactor } from "better-auth/plugins"
 
export const auth = betterAuth({
    // ... other config options
    appName: "My App", // provide your app name. It'll be used as an issuer.
    plugins: [
        twoFactor() 
    ]
})

npx @better-auth/cli migrate

import { createAuthClient } from "better-auth/client"
import { twoFactorClient } from "better-auth/client/plugins"
 
export const authClient = createAuthClient({
    plugins: [
        twoFactorClient()
    ]
})

Usage

Enabling 2FA

To enable two-factor authentication, call twoFactor.enable with the user's password and issuer (optional):

const { data } = await authClient.twoFactor.enable({
  password: "password", // user password required
  issuer: "my-app-name", // Optional, defaults to the app name
});

When 2FA is enabled:

• An encrypted secret and backupCodes are generated.
• enable returns totpURI and backupCodes.

Note: twoFactorEnabled won’t be set to true until the user verifies their TOTP code.

To verify, display the QR code for the user to scan with their authenticator app. After they enter the code, call verifyTotp:

await authClient.twoFactor.verifyTotp({
    code: "" // user input
})

Sign In with 2FA

When a user with 2FA enabled tries to sign in via email, the response will contain twoFactorRedirect set to true. This indicates that the user needs to verify their 2FA code.

await authClient.signIn.email({
    email: "user@example.com",
    password: "password123",
})

You can handle this in the onSuccess callback or by providing a onTwoFactorRedirect callback in the plugin config.

import { createAuthClient } from "better-auth/client";
import { twoFactorClient } from "better-auth/client/plugins";
 
const authClient = createAuthClient({
    plugins: [twoFactorClient({
        onTwoFactorRedirect(){
            // Handle the 2FA verification globally
        }
    })]
})

Or you can handle it in place:

await authClient.signIn.email({
        email: "user@example.com",
        password: "password123",
    }, {
        async onSuccess(context) {
            if (context.data.twoFactorRedirect) {
                // Handle the 2FA verification in place
            }
        }
    }
})

Using auth.api

When you call auth.api.signInEmail on the server, and the user has 2FA enabled, it will, by default, respond with an object where twoFactorRedirect is set to true. This behavior isn’t inferred in TypeScript, which can be misleading. We recommend passing asResponse: true to receive the Response object instead.

const response = await auth.api.signInEmail({
    email: "my-email@email.com",
    password: "secure-password",
    asResponse: true
})

Disabling 2FA

To disable two-factor authentication, call twoFactor.disable with the user's password:

const { data } = await authClient.twoFactor.disable({
    password: "password" // user password required
})

TOTP

TOTP (Time-Based One-Time Password) is an algorithm that generates a unique password for each login attempt using time as a counter. Every fixed interval (Better Auth defaults to 30 seconds), a new password is generated. This addresses several issues with traditional passwords: they can be forgotten, stolen, or guessed. OTPs solve some of these problems, but their delivery via SMS or email can be unreliable (or even risky, considering it opens new attack vectors).

TOTP, however, generates codes offline, making it both secure and convenient. You just need an authenticator app on your phone, and you’re set—no internet required.

Getting TOTP URI

After enabling 2FA, you can get the TOTP URI to display to the user. This URI is generated by the server using the secret and issuer and can be used to generate a QR code for the user to scan with their authenticator app.

const { data, error } = await authClient.twoFactor.getTotpUri({
    password: "password" // user password required
})

Example: Using React

import QRCode from "react-qr-code";
 
export default function UserCard(){
    const { data: session } = client.useSession();
	const { data: qr } = useQuery({
		queryKey: ["two-factor-qr"],
		queryFn: async () => {
			const res = await authClient.twoFactor.getTotpUri();
			return res.data;
		},
		enabled: !!session?.user.twoFactorEnabled,
	});
    return (
        <QRCode value={qr?.totpURI || ""} />
   )
}

Verifying TOTP

After the user has entered their 2FA code, you can verify it using twoFactor.verifyTotp method.

const verifyTotp = async (code: string) => {
    const { data, error } = await authClient.twoFactor.verifyTotp({ code })
}

OTP

OTP (One-Time Password) is similar to TOTP but a random code is generated and sent to the user's email or phone.

Before using OTP to verify the second factor, you need to configure sendOTP in your Better Auth instance. This function is responsible for sending the OTP to the user's email, phone, or any other method supported by your application.

import { betterAuth } from "better-auth"
import { twoFactor } from "better-auth/plugins"
 
export const auth = betterAuth({
    plugins: [
        twoFactor({
          	otpOptions: {
				async sendOTP({ user, otp }, request) {
                    // send otp to user
				},
			},
        })
    ]
})

Sending OTP

Sending an OTP is done by calling the twoFactor.sendOtp function. This function will trigger your sendOTP implementation that you provided in the Better Auth configuration.

const { data, error } = await authClient.twoFactor.sendOtp()
if (data) {
    // redirect or show the user to enter the code
}

Verifying OTP

After the user has entered their OTP code, you can verify it

const verifyOtp = async (code: string) => {
    await authClient.twoFactor.verifyOtp({ code }, {
        onSuccess(){
            //redirect the user on success
        },
        onError(ctx){
            alert(ctx.error.message)
        }
    })
}

Backup Codes

Backup codes are generated and stored in the database. This can be used to recover access to the account if the user loses access to their phone or email.

Generating Backup Codes

Generate backup codes for account recovery:

const { data, error } = await authClient.twoFactor.generateBackupCodes({
    password: "password" // user password required
})
if (data) {
    // Show the backup codes to the user
}

Using Backup Codes

You can now allow users to provider backup code as account recover method.

await authClient.twoFactor.verifyBackupCode({code: ""}, {
    onSuccess(){
        //redirect the user on success
    },
    onError(ctx){
        alert(ctx.error.message)
    }
})

once a backup code is used, it will be removed from the database and can't be used again.

Viewing Backup Codes

You can view the backup codes at any time by calling viewBackupCodes. This action can only be performed on the server using auth.api.

await auth.api.viewBackupCodes({
    body: {
        userId: "user-id"
    }
})

Trusted Devices

You can mark a device as trusted by passing trustDevice to verifyTotp or verifyOtp.

const verify2FA = async (code: string) => {
    const { data, error } = await authClient.twoFactor.verifyTotp({
        code,
        callbackURL: "/dashboard",
        trustDevice: true // Mark this device as trusted
    })
    if (data) {
        // 2FA verified and device trusted
    }
}

When trustDevice is set to true, the current device will be remembered for 60 days. During this period, the user won't be prompted for 2FA on subsequent sign-ins from this device. The trust period is refreshed each time the user signs in successfully.

Issuer

By adding an issuer you can set your application name for the 2fa application.

For example, if your user uses Google Auth, the default appName will show up as Better Auth. However, by using the following code, it will show up as my-app-name.

twoFactor({
    issuer: "my-app-name"
})

Schema

The plugin requires 1 additional fields in the user table and 1 additional table to store the two factor authentication data.

Table: twoFactor

Options

Server

twoFactorTable: The name of the table that stores the two factor authentication data. Default: twoFactor.

skipVerificationOnEnable: Skip the verification process before enabling two factor for a user.

Issuer: The issuer is the name of your application. It's used to generate TOTP codes. It'll be displayed in the authenticator apps.

TOTP options

these are options for TOTP.

OTP options

these are options for OTP.

Backup Code Options

backup codes are generated and stored in the database when the user enabled two factor authentication. This can be used to recover access to the account if the user loses access to their phone or email.

Client

To use the two factor plugin in the client, you need to add it on your plugins list.

import { createAuthClient } from "better-auth/client"
import { twoFactorClient } from "better-auth/client/plugins"
 
const authClient =  createAuthClient({
    plugins: [
        twoFactorClient({ 
            onTwoFactorRedirect(){
                window.location.href = "/2fa" // Handle the 2FA verification redirect
            }
        }) 
    ]
})

Options

onTwoFactorRedirect: A callback that will be called when the user needs to verify their 2FA code. This can be used to redirect the user to the 2FA page.