双重身份验证 (2FA)

OTP TOTP 备用代码 受信设备

双重身份验证 (2FA) 在用户登录时增加了一道额外的安全步骤。用户不仅需要密码，还需提供第二种验证方式。这使得即使密码泄露，未经授权的人也更难访问账户。

此插件提供两种主要的二次验证方法：

1. OTP (一次性密码)：发送到用户邮箱或手机的临时代码。
2. TOTP (基于时间的一次性密码)：由用户设备上的应用生成的代码。

附加功能包括：

• 生成备用代码用于账户恢复

• 启用/禁用 2FA

• 管理受信设备

• 生成备用代码用于账户恢复

• 启用/禁用 2FA

• 管理受信设备

安装

import { betterAuth } from "better-auth"
import { twoFactor } from "better-auth/plugins"

export const auth = betterAuth({
    // ... 其他配置选项
    appName: "My App", // 提供您的应用名称。这将用作颁发者。
    plugins: [
        twoFactor() 
    ]
})

npx auth migrate

npx auth generate

import { createAuthClient } from "better-auth/client"
import { twoFactorClient } from "better-auth/client/plugins"

export const authClient = createAuthClient({
    plugins: [
        twoFactorClient() 
    ]
})

使用

启用 2FA

要启用双重身份验证，请使用用户的密码（凭证账户必填）和发布者（可选）调用 twoFactor.enable。如果启用了 allowPasswordless，对于没有凭证账户的用户可以省略密码。

const { data, error } = await authClient.twoFactor.enable({    password: "secure-password",    issuer: "my-app-name",});

const data = await auth.api.enableTwoFactor({    body: {        password: "secure-password",        issuer: "my-app-name",    },    // This endpoint requires session cookies.    headers: await headers(),});

启用 2FA 后：

• 生成加密的 secret 和 backupCodes。
• enable 返回 totpURI 和 backupCodes。

注意：在用户验证其 TOTP 代码之前，twoFactorEnabled 不会被设置为 true。有关在 TOTP 部分 验证 TOTP 的更多信息。如果您在插件配置中将 skipVerificationOnEnable 设置为 true，则可以跳过验证。

使用 2FA 登录

当启用了 2FA 的用户尝试通过邮箱、用户名或手机号登录时，响应对象将包含设置为 true 的 twoFactorRedirect，以及 twoFactorMethods——一个包含该用户可用 2FA 方法的数组（例如 ["totp"]、["totp", "otp"]）。使用 twoFactorMethods 来决定显示哪种验证界面。

默认情况下，2FA 登录强制适用于基于凭证的登录端点：/sign-in/email、/sign-in/username 和 /sign-in/phone-number。诸如邮箱 OTP、magic link、OAuth/社交登录、passkey、匿名登录以及类似的无密码流程，默认不会被 2FA 限制。

如果您的应用需要对这些登录方式也强制要求 2FA，请为这些端点添加自定义 hook 处理，并在将登录视为完成之前，把用户重定向到您的 2FA 验证流程中。

您可以在 onSuccess 回调中处理，或在插件配置中提供 onTwoFactorRedirect 回调。

import { authClient } from "@/lib/auth-client"

await authClient.signIn.email({
        email: "user@example.com",
        password: "password123",
    },
    {
        async onSuccess(context) {
            if (context.data.twoFactorRedirect) {
                const methods = context.data.twoFactorMethods // 例如 ["totp", "otp"]
                // 根据可用的方法显示适当的 2FA 验证 UI
            }
        },
    }
)

使用 onTwoFactorRedirect 配置示例：

import { createAuthClient } from "better-auth/client";
import { twoFactorClient } from "better-auth/client/plugins";

const authClient = createAuthClient({
    plugins: [
        twoFactorClient({
            onTwoFactorRedirect({ twoFactorMethods }){
                // twoFactorMethods 例如 ["totp", "otp"]
                // 在全局处理 2FA 验证
            },
        }),
    ],
});

使用 twoFactorPage 配置：

import { createAuthClient } from "better-auth/client";
import { twoFactorClient } from "better-auth/client/plugins";

const authClient = createAuthClient({
    plugins: [
        twoFactorClient({
            twoFactorPage: "/two-factor", // 如果用户需要验证第二因素，重定向到该页面
        }),
    ],
});

import { auth } from "@/lib/auth"

const { headers: responseHeaders, response } = await auth.api.signInEmail({
	returnHeaders: true,
	body: {
		email: "test@test.com",
		password: "test",
	},
});

if ("twoFactorRedirect" in response) {
	// response.twoFactorMethods 例如 ["totp", "otp"]
	// 将 responseHeaders 中的 cookie 传递到下一个 auth.api 2FA 调用。
	// 在适当的位置处理 2FA 验证
}

禁用 2FA

要禁用双重身份验证，请使用用户的密码（凭证账户必填）调用 twoFactor.disable。如果启用了 allowPasswordless，对于没有凭证账户的用户可以省略密码。

const { data, error } = await authClient.twoFactor.disable({    password,});

const data = await auth.api.disableTwoFactor({    body: {        password,    },    // This endpoint requires session cookies.    headers: await headers(),});

TOTP

TOTP（基于时间的一次性密码）是一种使用时间计数器为每次登录生成唯一密码的算法。每隔固定时间（Better Auth 默认为 30 秒）生成一个新密码。它解决了传统密码可能被遗忘、窃取或猜测的问题。虽然 OTP 也解决了一部分问题，但通过短信或邮箱发送 OTP 的可靠性较差（甚至更有风险，因为它可能带来新的攻击面）。

而 TOTP 是离线生成代码，既安全又便捷。只需在手机上安装认证器应用即可。

获取 TOTP URI

启用 2FA 后，可以获取 TOTP URI 并向用户展示。该 URI 是服务器基于 secret 和 issuer 生成的，用于生成二维码，供用户用认证器扫描。

const { data, error } = await authClient.twoFactor.getTotpUri({    password,});

const data = await auth.api.getTOTPURI({    body: {        password,    },    // This endpoint requires session cookies.    headers: await headers(),});

示例：使用 React

获取到 TOTP URI 后，可以将其用于生成二维码，供用户使用认证器应用扫描。

import { authClient } from "@/lib/auth-client"
import QRCode from "react-qr-code";

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

验证 TOTP

用户输入 2FA 代码后，可以调用 twoFactor.verifyTotp 方法进行验证。Better Auth 遵循标准做法，接受当前时间段前后各一个周期内的代码，确保用户即使存在轻微时间偏差也可成功认证。

const { data, error } = await authClient.twoFactor.verifyTotp({    code: "012345", // required    trustDevice: true,});

const data = await auth.api.verifyTOTP({    body: {        code: "012345", // required        trustDevice: true,    },    // 传递当前请求标头，以便 Better Auth 可以读取并设置 2FA/session cookie。    headers: await headers(),});

OTP

OTP（一次性密码）与 TOTP 类似，但生成的随机码会通过邮件或短信发送给用户。

在使用 OTP 进行二次验证之前，您需要在 Better Auth 实例中配置 sendOTP。该函数负责将 OTP 发送给用户的邮箱、手机或其他支持的方式。

import { betterAuth } from "better-auth"
import { twoFactor } from "better-auth/plugins"

export const auth = betterAuth({
    plugins: [
        twoFactor({
          	otpOptions: {
				async sendOTP({ user, otp }, ctx) {
                    // 向用户发送 otp
				},
			},
        })
    ]
})

发送 OTP

发送 OTP 通过调用客户端的 authClient.twoFactor.sendOtp 函数或服务器端的 auth.api.sendTwoFactorOTP 完成。该函数会触发您在 Better Auth 配置中提供的 sendOTP 实现。

const { data, error } = await authClient.twoFactor.sendOtp({    trustDevice: true,});if (data) {    // 重定向或显示用户输入代码的界面}

const data = await auth.api.sendTwoFactorOTP({    body: {        trustDevice: true,    },    // 传递当前请求标头，以便 Better Auth 可以读取并设置 2FA/session cookie。    headers: await headers(),});if (data) {    // 重定向或显示用户输入代码的界面}

验证 OTP

用户输入 OTP 代码后，您可以使用客户端的 authClient.twoFactor.verifyOtp 或服务器端的 auth.api.verifyTwoFactorOTP 进行验证。

const { data, error } = await authClient.twoFactor.verifyOtp({    code: "012345", // required    trustDevice: true,});

const data = await auth.api.verifyTwoFactorOTP({    body: {        code: "012345", // required        trustDevice: true,    },    // 传递当前请求标头，以便 Better Auth 可以读取并设置 2FA/session cookie。    headers: await headers(),});

备用代码

备用代码存储于数据库。当用户失去手机或邮箱访问权限时，可用于账户恢复。

生成备用代码

为账户恢复生成备用代码：

const { data, error } = await authClient.twoFactor.generateBackupCodes({    password,});if (data) {    // 向用户展示备用代码}

const data = await auth.api.generateBackupCodes({    body: {        password,    },    // This endpoint requires session cookies.    headers: await headers(),});if (data) {    // 向用户展示备用代码}

使用备用代码

您可以允许用户使用备用代码作为账户恢复方式。

const { data, error } = await authClient.twoFactor.verifyBackupCode({    code: "123456", // required    disableSession: false,    trustDevice: true,});

const data = await auth.api.verifyBackupCode({    body: {        code: "123456", // required        disableSession: false,        trustDevice: true,    },    // 传递当前请求标头，以便 Better Auth 可以读取并设置 2FA/session cookie。    headers: await headers(),});

查看备用代码

要向用户展示备用代码，可以在服务器调用 viewBackupCodes，返回备用代码。请确保仅允许拥有刚创建的新鲜会话的用户执行此操作。

const { data, error } = await authClient.twoFactor.viewBackupCodes({    userId: "user-id",});

const data = await auth.api.viewBackupCodes({    body: {        userId: "user-id",    },});

受信设备

您可以通过向 verifyTotp 或 verifyOtp 传入 trustDevice 来标记设备为受信设备。

const verify2FA = async (code: string) => {
    const { data, error } = await authClient.twoFactor.verifyTotp({
        code,
        trustDevice: true, // 将当前设备标记为受信设备
    })
    if (data) {
        // 2FA 验证成功且设备被标记为受信
    }
}

当 trustDevice 设置为 true，当前设备将在 30 天内被记为受信设备。在此期间，用户通过该设备再次登录时不会被提示进行 2FA 验证。每次成功登录都会刷新该受信期限。

发布者（Issuer）

通过添加 issuer，您可以设置应用名称，该名称会显示在 2FA 应用中。

例如，若用户使用 Google Auth，默认 appName 会显示为 Better Auth。您可如下配置，使其显示为 my-app-name。

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

模式 (Schema)

该插件需要在 user 表中添加 1 个额外字段，且新增 1 个表用于存储双重身份验证数据。

表：user

表：twoFactor

配置选项

服务器端

twoFactorTable：存储双重身份验证数据的表名。默认值：twoFactor。

skipVerificationOnEnable：在启用用户的双重身份验证时，跳过验证过程。

allowPasswordless：允许对没有凭据账户的用户在没有密码的情况下启用和管理 2FA。如果存在凭据账户，则仍然需要密码。此选项不会更改哪些登录方式会在 2FA 时被质询。

Issuer：签发者是您的应用程序名称。它用于生成 TOTP 代码，并会显示在身份验证器应用中。

TOTP 选项

TOTP 的相关配置。

OTP Options

OTP-related configuration.

备用代码选项

当用户启用双因素认证时，备用代码会在数据库中生成并存储。如果用户无法访问其手机或电子邮件，这些代码可用于恢复对账户的访问。

备用代码选项

当用户启用双重身份验证时，备用代码会被生成并存储，用于在用户无法访问手机或邮箱时恢复账户。

客户端

在客户端使用双重身份验证插件时，需要将其添加到插件列表中。

import { createAuthClient } from "better-auth/client"
import { twoFactorClient } from "better-auth/client/plugins"

const authClient =  createAuthClient({
    plugins: [
        twoFactorClient({ 
            onTwoFactorRedirect({ twoFactorMethods }){ 
                // twoFactorMethods 例如 ["totp", "otp"]
                window.location.href = "/2fa" // 处理 2FA 验证重定向
            } 
        }) 
    ]
})

选项

onTwoFactorRedirect：当用户需要验证其双重身份验证代码时调用的回调函数。接收一个包含 twoFactorMethods 的上下文对象——一个已启用的双重身份验证方法数组（例如 ["totp", "otp"]）。这可用于将用户重定向到适当的 2FA 页面。