Two-Factor Authentication

Setup and use two-factor authentication (2FA) for enhanced security with TOTP-based verification

Overview

SaaS Starter Vue includes built-in two-factor authentication (2FA) using Laravel Fortify’s implementation. This provides an additional layer of security by requiring users to verify their identity with a time-based one-time password (TOTP) in addition to their password.

2FA uses authenticator apps like Google Authenticator, Authy, or 1Password to generate verification codes.

How It Works

2FA requires users to:

1. Enter their email and password (first factor)
2. Enter a 6-digit code from their authenticator app (second factor)
3. Optionally use recovery codes if they lose access to their authenticator

TOTP (Time-Based One-Time Password)

The system uses the TOTP algorithm (RFC 6238) which generates codes that expire every 30 seconds. This is the same standard used by Google Authenticator and other popular authenticator apps.

Configuration

Enable 2FA Feature

2FA is enabled in the Fortify configuration:

// config/fortify.php:146
'features' => [
    Features::twoFactorAuthentication([
        'confirm' => true,
        'confirmPassword' => true,
    ]),
],

Options:

confirm · boolean · default: "true"

Require users to confirm 2FA setup with a valid code before activation

confirmPassword · boolean · default: "true"

Require password confirmation before enabling/disabling 2FA

Database Schema

The users table includes 2FA columns:

// database/migrations/2025_08_14_170933_add_two_factor_columns_to_users_table.php:14
Schema::table('users', function (Blueprint $table) {
    $table->text('two_factor_secret')->after('password')->nullable();
    $table->text('two_factor_recovery_codes')->after('two_factor_secret')->nullable();
    $table->timestamp('two_factor_confirmed_at')->after('two_factor_recovery_codes')->nullable();
});

two_factor_secret · text

Encrypted TOTP secret key used to generate verification codes

two_factor_recovery_codes · text

Encrypted JSON array of one-time recovery codes

two_factor_confirmed_at · timestamp

Timestamp when 2FA was successfully confirmed and activated

User Model Setup

The User model includes the TwoFactorAuthenticatable trait:

// app/Models/System/User.php:12
class User extends Authenticatable
{
    use HasApiTokens, HasFactory, Notifiable, TwoFactorAuthenticatable;

    protected $hidden = [
        'password',
        'two_factor_secret',
        'two_factor_recovery_codes',
        'remember_token',
    ];

    protected function casts(): array
    {
        return [
            'email_verified_at' => 'datetime',
            'password' => 'hashed',
            'two_factor_confirmed_at' => 'datetime',
        ];
    }
}

Never expose two_factor_secret or two_factor_recovery_codes in API responses. They are automatically hidden.

Enabling 2FA

Step-by-Step Setup

1. Navigate to Security Settings

   Users access their security settings page (typically /settings/security)

2. Confirm Password

   User enters their current password to authorize 2FA changes

3. Enable Two-Factor

   User clicks “Enable Two-Factor Authentication”

   POST /auth/user/two-factor-authentication
   
4. Scan QR Code

   System generates and displays a QR code. User scans it with their authenticator app

   GET /auth/user/two-factor-qr-code
   
5. Verify Setup

   User enters a code from their authenticator app to confirm setup

6. Save Recovery Codes

   System generates 8 recovery codes. User must save them securely

   GET /auth/user/two-factor-recovery-codes
   

API Endpoints

Enable 2FA

// routes/web.php:215
Route::post('/user/two-factor-authentication', [TwoFactorAuthenticationController::class, 'store'])
    ->middleware($twoFactorMiddleware)
    ->name('two-factor.enable');

This endpoint:

• Generates a new TOTP secret
• Creates recovery codes
• Stores encrypted secret in database

Get QR Code

// routes/web.php:227
Route::get('/user/two-factor-qr-code', [TwoFactorQrCodeController::class, 'show'])
    ->middleware($twoFactorMiddleware)
    ->name('two-factor.qr-code');

Returns an SVG QR code that users scan with their authenticator app.

Get Secret Key

// routes/web.php:231
Route::get('/user/two-factor-secret-key', [TwoFactorSecretKeyController::class, 'show'])
    ->middleware($twoFactorMiddleware)
    ->name('two-factor.secret-key');

Provides the secret key as text for manual entry if QR scanning isn’t available.

Get Recovery Codes

// routes/web.php:235
Route::get('/user/two-factor-recovery-codes', [RecoveryCodeController::class, 'index'])
    ->middleware($twoFactorMiddleware)
    ->name('two-factor.recovery-codes');

Displays the recovery codes for users to save.

Regenerate Recovery Codes

// routes/web.php:219
Route::post('/user/two-factor-recovery-codes', [RecoveryCodeController::class, 'store'])
    ->middleware($twoFactorMiddleware)
    ->name('two-factor.recovery-codes.store');

Generates new recovery codes (invalidates old ones).

Disabling 2FA

Users can disable 2FA:

// routes/web.php:223
Route::delete('/user/two-factor-authentication', [TwoFactorAuthenticationController::class, 'destroy'])
    ->middleware($twoFactorMiddleware)
    ->name('two-factor.disable');

1. Navigate to Security Settings

   Access the security settings page

2. Confirm Password

   Enter current password to authorize the change

3. Disable 2FA

   Click “Disable Two-Factor Authentication”

4. Confirmation

   2FA is immediately disabled and secret/codes are removed from database

Disabling 2FA reduces account security. Warn users before allowing them to disable it, especially for admin accounts.

Login with 2FA

Two-Factor Challenge Flow

When 2FA is enabled, the login process changes:

1. Enter Credentials

   User enters email and password at /auth/login

2. Redirect to 2FA Challenge

   Instead of logging in, user is redirected to /auth/two-factor-challenge

   // routes/web.php:203
   Route::get('/two-factor-challenge', [TwoFactorAuthenticatedSessionController::class, 'create'])
       ->middleware(['guest:'.config('fortify.guard')])
       ->name('two-factor.login');
   
3. Enter Verification Code

   User enters the 6-digit code from their authenticator app (or a recovery code)

4. Submit Challenge

   POST /auth/two-factor-challenge
   

   With either:

   {"code": "123456"}
   

   or

   {"recovery_code": "recovery-code-here"}
   
5. Login Successful

   User is authenticated and redirected to dashboard

Challenge Endpoint

// routes/web.php:208
Route::post('/two-factor-challenge', [TwoFactorAuthenticatedSessionController::class, 'store'])
    ->middleware(['guest:'.config('fortify.guard')]);

Request Body (Code):

{
  "code": "123456"
}

Request Body (Recovery Code):

{
  "recovery_code": "ABCD-EFGH-IJKL-MNOP"
}

Rate Limiting

2FA challenges are rate-limited separately:

// config/fortify.php:117
'limiters' => [
    'login' => 'login',
    'two-factor' => 'two-factor',
],

This prevents brute force attacks on verification codes.

Recovery Codes

What Are Recovery Codes?

Recovery codes are one-time use backup codes that allow users to access their account if they:

• Lose their authenticator device
• Can’t access their authenticator app
• Need emergency access

Recovery Code Format

By default, Laravel Fortify generates 8 recovery codes that look like:

ABCD-EFGH-IJKL-MNOP
QRST-UVWX-YZAB-CDEF
...

Using Recovery Codes

Users can enter a recovery code instead of a TOTP code during login:

1. Click “Use recovery code” on the 2FA challenge page
2. Enter one of their saved recovery codes
3. Code is validated and invalidated (can only be used once)
4. User is logged in

Once a recovery code is used, it’s permanently invalidated. Users should regenerate recovery codes after using them.

Regenerating Recovery Codes

Users should regenerate codes if:

• They’ve used some recovery codes
• They suspect codes were compromised
• They want to invalidate old codes

POST /auth/user/two-factor-recovery-codes

Security Considerations

Password Confirmation

Sensitive 2FA operations require password confirmation:

// routes/web.php:211
$twoFactorMiddleware = Features::optionEnabled(Features::twoFactorAuthentication(), 'confirmPassword')
    ? [config('fortify.auth_middleware', 'auth').':'.config('fortify.guard'), 'password.confirm']
    : [config('fortify.auth_middleware', 'auth').':'.config('fortify.guard')];

This prevents attackers from enabling/disabling 2FA if they gain temporary access to an authenticated session.

Best Practices

Critical Security Recommendations:

1. Always require password confirmation for 2FA changes
2. Force 2FA for admin/privileged accounts
3. Educate users to save recovery codes securely
4. Monitor failed 2FA attempts for suspicious activity
5. Consider backup authentication methods

Enforcing 2FA

You can require 2FA for specific users or roles:

// Middleware to enforce 2FA
class RequireTwoFactorAuth
{
    public function handle($request, Closure $next)
    {
        $user = $request->user();
        
        if (!$user->two_factor_secret) {
            return redirect()->route('settings.security')
                ->with('error', 'You must enable two-factor authentication to access this resource.');
        }
        
        return $next($request);
    }
}

Apply to sensitive routes:

Route::middleware(['auth', 'require.2fa'])->group(function () {
    Route::get('/admin', [AdminController::class, 'index']);
});

Checking 2FA Status

In your blade/Vue templates:

@if(auth()->user()->two_factor_secret)
    <span class="badge badge-success">2FA Enabled</span>
@else
    <span class="badge badge-warning">2FA Disabled</span>
@endif

In controllers:

if ($user->two_factor_secret) {
    // 2FA is enabled
}

if ($user->two_factor_confirmed_at) {
    // 2FA is confirmed and active
}

Testing 2FA

Test 2FA in your application:

use Laravel\Fortify\Actions\GenerateNewRecoveryCodes;
use PragmaRX\Google2FA\Google2FA;

// Generate a valid code for testing
$user = User::factory()->create();
$user->forceFill([
    'two_factor_secret' => encrypt($secret = app(Google2FA::class)->generateSecretKey()),
])->save();

$code = app(Google2FA::class)->getCurrentOtp(
    decrypt($user->two_factor_secret)
);

// Test login with 2FA
$this->post('/auth/login', [
    'email' => $user->email,
    'password' => 'password',
]);

$this->post('/auth/two-factor-challenge', [
    'code' => $code,
])->assertRedirect('/dashboard');

Troubleshooting

Codes not working

Common causes:

1. Time sync issues - Ensure device clock is accurate (TOTP is time-based)
2. Wrong secret - User may have scanned QR code for different account
3. App issues - Try different authenticator app

Solution: Disable and re-enable 2FA with fresh QR code

Lost authenticator device

Options:

1. Use a recovery code to log in
2. Contact support to disable 2FA (requires identity verification)
3. Use backup authenticator if codes were synced (like Authy)

Prevention: Always save recovery codes when setting up 2FA

QR code not displaying

Check:

1. User is authenticated
2. 2FA is enabled for the user (two_factor_secret exists)
3. Route middleware is correct
4. SVG rendering is supported in browser

Customization

You can customize the 2FA experience:

Custom 2FA Views

Create custom Inertia/Vue pages:

return Inertia::render('Auth/TwoFactorChallenge', [
    'message' => 'Enter the code from your authenticator app',
]);

Custom Recovery Code Count

Modify the recovery code generation in a service provider:

use Laravel\Fortify\Actions\GenerateNewRecoveryCodes;

app()->bind(GenerateNewRecoveryCodes::class, function () {
    return new GenerateNewRecoveryCodes(16); // Generate 16 codes instead of 8
});

Backup Methods

Consider implementing backup authentication methods:

• SMS verification (requires additional package)
• Email verification codes
• Hardware security keys (WebAuthn)

Related Documentation

• Authentication System - General authentication overview
• User Management - Managing users and permissions
• Security Best Practices - Overall security guidelines