two-factor/options

9 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Two-Factor plugin server options

Server options: twoFactorTable (string, default 'twoFactor', table name for 2FA data), skipVerificationOnEnable (boolean, skip verification before enabling 2FA), allowPasswordless (boolean, allow enabling/managing 2FA without password for non-credential users; password still required if credential account exists), issuer (string, application name for TOTP, displayed in authenticator apps).

Two-Factor TOTP options

TOTP options in 2FA plugin: digits (number, default 6, number of digits for OTP), period (number, default 30, period for TOTP in seconds).

Two-Factor OTP options

OTP options in 2FA plugin: sendOTP (function, required, sends OTP to user's email or phone, takes user and otp parameters), period (number, default 3, period for OTP in minutes), storeOTP (string, default 'plain', how to transform stored OTP - plain text, encrypted, or hashed with custom encryptor/hasher options).

Two-Factor backup code options

Backup code options in 2FA plugin: amount (number, default 10, number of backup codes to generate), length (number, default 10, length of backup codes), customBackupCodesGenerate (function, generates custom backup codes, takes no parameters and returns array of strings), storeBackupCodes (string, default 'plain', how to store backup codes - plain text or encrypted with custom encryptor options).

Two-Factor account lockout options

Account lockout options in 2FA plugin (enabled by default): enabled (boolean, default true, whether account-level lockout is enforced), maxFailedAttempts (number, default 10, consecutive failed verifications across challenges and factors before account is locked), durationSeconds (number, default 900, how long account stays locked in seconds). Locked attempts return 429 with ACCOUNT_TEMPORARILY_LOCKED error. Limit applies per account across TOTP, OTP, and backup codes.

Two-Factor client plugin options

Client plugin option: onTwoFactorRedirect (callback function called when user needs to verify 2FA, receives context object with twoFactorMethods array - e.g. ['totp', 'otp'] - of enabled 2FA methods, used to redirect user to appropriate 2FA page).

Two-Factor allowPasswordless configuration

By default, the 2FA plugin requires a credential (password) account. To allow passwordless users (passkeys, magic links, email OTP, OAuth/social, or anonymous) to enable and manage 2FA, set allowPasswordless: true in plugin config. This option does not change which sign-in methods are challenged for 2FA.

Two-Factor issuer configuration

By default the issuer for TOTP is set to the app name provided in the auth config, or if not provided it will be set to 'Better Auth'. Override by passing issuer to plugin config: twoFactor({ issuer: 'my-app-name' }).

twoFactorPage client configuration pitfall

Using the twoFactorPage option in client config causes a full page reload when redirecting users to the two-factor authentication page. To avoid page reloads, use the onTwoFactorRedirect callback instead to handle the redirect programmatically within your application.

Give your agent this brain