Two-Factor Authentication

The TwoFactorPlugin adds two-factor authentication (2FA) to your application. It supports TOTP (authenticator apps), OTP (email-based one-time passwords), and backup codes for recovery.

Setup

These examples assume you've already defined AppAuthSchema. If you want a complete setup from entity definitions through Axum mounting, start with the Axum integration guide.

use better_auth::plugins::TwoFactorPlugin;

let auth = BetterAuth::<AppAuthSchema>::new(config)
    .store(store)
    .plugin(TwoFactorPlugin::new())
    .build()
    .await?;

Configuration

use better_auth::plugins::two_factor::TwoFactorConfig;
use std::sync::Arc;

let auth = BetterAuth::<AppAuthSchema>::new(config)
    .store(store)
    .plugin(
        TwoFactorPlugin::new().with_config(TwoFactorConfig {
            issuer: Some("My App".to_string()),
            skip_verification_on_enable: false,
            two_factor_cookie_max_age: 600,
            trust_device_max_age: 30 * 24 * 60 * 60,
            totp_period: 30,
            totp_digits: 6,
            send_otp: None,
        })
    )
    .build()
    .await?;

How It Works

Enrollment Flow

1. User calls /two-factor/enable with their password
2. An encrypted TOTP secret is generated and stored
3. Backup codes are generated and stored as encrypted JSON
4. User scans the TOTP URI in their authenticator app
5. twoFactorEnabled remains false until verification unless skip_verification_on_enable is enabled

Sign-In Flow with 2FA

1. User signs in with email/password as normal
2. If 2FA is enabled, instead of creating a session, a pending verification is created
3. User must verify with one of:
   • TOTP: Code from authenticator app
   • OTP: Code sent via email
   • Backup code: One-time recovery code
4. After successful verification, a session is created

API Endpoints

The 2FA plugin exposes the following endpoints. For full request/response details, see the OpenAPI Reference.

Security Details

• TOTP secrets are encrypted before being stored in the database
• Backup codes are stored as encrypted JSON — the plaintext is only returned once during generation
• OTP codes are stored as verification records and expire after 3 minutes
• Password verification is required to enable/disable 2FA and to regenerate backup codes
• Used backup codes are immediately removed from the stored set

Errors