better-auth/双因素认证最佳实践

双因素认证最佳实践 是做什么的？

使用 Better Auth 的 twoFactor 插件配置 TOTP 验证器应用，通过电子邮件/短信发送 OTP 码，管理备用验证码，处理受信任设备，并实现 2FA 登录流程。在用户需要 MFA、多因素认证、验证器设置或使用 Better Auth 进行登录安全时使用。

概述

本指南涵盖使用 Better Auth 的 twoFactor 插件配置双因素认证 (2FA) 的最佳实践。2FA 通过在用户密码之外增加第二个验证步骤，显著提升帐户安全性。

twoFactor 插件支持：

• 基于时间的一次性密码 (TOTP)：与 Google Authenticator、Authy、Microsoft Authenticator 等验证器应用兼容。
• 一次性密码 (OTP)：通过电子邮件或 SMS 发送代码，方便使用。
• 备用验证码：供用户在无法访问主要 2FA 方法时使用的恢复机制。
• 受信任设备：允许用户在特定设备上跳过 2FA 提示（可选）。

安装与设置

npm install better-auth

初始化 Better Auth 并启用 twoFactor 插件：

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

export const auth = betterAuth({
  plugins: [
    twoFactor(),
  ],
})

配置选项

选项	类型	默认值	描述
otpOptions	object	{}	OTP 传递选项（电子邮件、SMS）
trustedDevice	boolean	false	允许设备被标记为受信任
backupCodes	boolean	true	在注册 2FA 时生成备用验证码
totp	boolean	true	启用 TOTP 支持

用法

1. 注册 TOTP

要设置 TOTP，你需要首先生成一个密钥，将其以二维码形式呈现给用户，然后验证用户正确配置了验证器。

// 生成 TOTP 注册选项
const response = await auth.api.generateTwoFactorRegistration({
  headers: request.headers,
})

// response.secret 包含共享密钥
// response.qrCode 包含用于用户扫描的 QR 码数据 URI

// 完成注册（用户验证码后）
const success = await auth.api.activateTwoFactor({
  headers: request.headers,
  body: {
    code: "用户输入的 TOTP 码",
  },
})

2. 使用 2FA 登录

登录工作流需要用户在密码验证后提供第二个因素：

// 步骤 1：标准凭据登录
const signInResult = await auth.api.signIn({
  body: {
    email: "[email protected]",
    password: "secure-password",
  },
})

// 如果启用了 2FA，响应将包含 `twoFactorRedirect: true` 和 `sessionToken`

// 步骤 2：验证第二个因素
const verifyResult = await auth.api.signInTwoFactor({
  body: {
    code: "验证器生成的 TOTP 码",
    // 或 totpCode/otpCode/backupCode 具体
    sessionToken: signInResult.sessionToken, // 来自第一步的会话令牌
  },
})

3. 发送 OTP 码

使用 OTP 而不是 TOTP 进行 2FA：

// 发送 OTP 码到用户的电子邮件/SMS
const sendOtpResult = await auth.api.sendTwoFactorOTP({
  headers: request.headers,
})

// 使用 OTP 码验证
const verifyOtpResult = await auth.api.verifyTwoFactorOTP({
  body: {
    code: "收到的 OTP 码",
    sessionToken: "第一步的会话令牌",
  },
})

4. 管理备用验证码

在注册 2FA 时，会自动生成备用验证码。它们应存储以备恢复：

// 获取备用验证码（注册后）
const backupCodesData = await auth.api.getTwoFactorBackupCodes({
  headers: request.headers,
})

// 使用备用验证码登录
const verifyWithBackup = await auth.api.signInTwoFactor({
  body: {
    backupCode: "用户提供的备用码",
    sessionToken: "第一步的会话令牌",
  },
})

5. 管理受信任设备

通过允许用户将设备标记为受信任来减少 2FA 提示：

// 在验证 2FA 时启用“记住此设备”
const verifyResult = await auth.api.signInTwoFactor({
  body: {
    code: "TOTP 或 OTP 码",
    sessionToken: "会话令牌",
    rememberDevice: true, // 可选：信任此设备
  },
})

最佳实践

1. 备用验证码至关重要：始终在注册过程中披露并安全存储备用验证码。为用户提供下载或复制它们的选项。
2. 清晰的用户引导：提供逐步设置说明，包括指向应用的二维码和验证码输入输入框。
3. 错误处理：优雅地处理无效验证码、过期会话和速率限制。提供用户友好的错误信息。
4. 选择加入与强制：考虑允许用户在自愿基础上启用 MFA，或使成为安全角色（如管理员）的强制性要求。
5. 恢复流程：实施使用备用验证码或管理能力的恢复流程，以在用户丢失设备时重置 2FA。

故障排除

• 确保 SECRET_KEY 环境变量已设置，以便安全生成 TOTP 密钥。
• 在使用 OTP 发送时，确保正确配置了 SMTP 或 SMS 提供者。
• 验证器的系统时间必须同步，以便 TOTP 码正常生成。

有关详细 API 参考，请参阅 Better Auth twoFactor 插件文档。