Multi-Factor Authentication (MFA)
Multi-Factor Authentication (MFA) adds an extra layer of security by requiring users to provide two forms of verification before accessing their accounts. The starter supports Time-Based One-Time Passwords (TOTP) natively using Better Auth.
Multi-Factor Authentication (MFA) adds an extra layer of security by requiring users to provide two forms of verification before accessing their accounts. The starter supports Time-Based One-Time Passwords (TOTP) natively using Better Auth.
Configuration
MFA is enabled via the twoFactor plugin in packages/backend/convex/auth.ts:
plugins: [
// ...
// TOTP issuer defaults to the appName configured above. Passwordless
// accounts can manage 2FA without entering a password they never set.
twoFactor({ allowPasswordless: true }),
]How It Works
- Setup: The user opts into MFA from their account settings. The application generates a TOTP secret and presents a QR code.
- Authenticator App: The user scans the QR code with an authenticator app (like Authy, Google Authenticator, or 1Password).
- Verification: The user enters the code generated by their app to confirm setup.
- Login: On subsequent logins, after providing their primary credential (password, magic link, or OAuth), the user is prompted to enter a TOTP code from their app.
Passwordless Accounts
By setting allowPasswordless: true, users who only authenticate via Magic Links or OAuth providers can still secure their accounts with MFA without being forced to create a password first. The TOTP issuer displayed in their authenticator app is configured via the appName parameter in betterAuth.
Sessions
Better Auth handles session management automatically, creating and managing secure sessions when a user authenticates.
Two-Factor Authentication Scope
When implementing Two-Factor Authentication (2FA) or Multi-Factor Authentication (MFA), it's important to understand the scope and how it affects the user session.