{"id":562,"date":"2025-09-01T02:57:00","date_gmt":"2025-09-01T02:57:00","guid":{"rendered":"https:\/\/1v0.net\/blog\/?p=562"},"modified":"2025-09-01T02:57:04","modified_gmt":"2025-09-01T02:57:04","slug":"laravel-fortify-2fa-example-enable-challenge-recovery-codes-step-by-step","status":"publish","type":"post","link":"https:\/\/1v0.net\/blog\/laravel-fortify-2fa-example-enable-challenge-recovery-codes-step-by-step\/","title":{"rendered":"Laravel Fortify 2FA Example: Enable, Challenge, Recovery Codes (Step by Step)"},"content":{"rendered":"\n

Laravel Fortify provides a headless authentication backend, including built-in Two-Factor Authentication (2FA) with time-based one-time passwords (TOTP). In this guide, you\u2019ll install and configure Fortify, enable 2FA, build minimal Blade views for enabling\/disabling 2FA, display QR codes and recovery codes, handle the two-factor challenge at login, wire useful events, and test the flow end-to-end.<\/p>\n\n\n\n

<\/div>\n\n\n\n\n

Install & Register Laravel Fortify<\/strong><\/h2>\n\n\n
composer require laravel\/fortify<\/code><\/span>Code language:<\/span> Bash<\/span> (<\/span>bash<\/span>)<\/span><\/small><\/pre>\n\n\n
This installs Fortify into your Laravel app. Fortify exposes authentication routes and actions (login, logout, 2FA enable\/disable, challenges) without generating UI scaffolding.<\/p>\n\n\n
php artisan vendor:publish --provider=\"Laravel\\Fortify\\FortifyServiceProvider\"<\/span><\/code><\/span>Code language:<\/span> Bash<\/span> (<\/span>bash<\/span>)<\/span><\/small><\/pre>\n\n\n
Publishing copies the Fortify configuration file, migrations, and language lines to your project so you can customize them (including the 2FA-related columns).<\/p>\n\n\n
\/\/ config\/app.php (ensure provider is registered if not auto-discovered)<\/span>\n'providers'<\/span> => [\n    \/\/ ...<\/span>\n    App\\Providers\\FortifyServiceProvider::class,\n],<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Fortify is typically registered via your own App\\Providers\\FortifyServiceProvider<\/code> so you can define views and behaviors. If you don\u2019t have it, create and register it as above.<\/p>\n\n\n
php artisan migrate<\/code><\/span>Code language:<\/span> Bash<\/span> (<\/span>bash<\/span>)<\/span><\/small><\/pre>\n\n\n
Run migrations to ensure 2FA columns exist on the users table. The published migration adds two_factor_secret<\/code>, two_factor_recovery_codes<\/code>, and timestamps needed for 2FA.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
Enable Two-Factor Authentication in Fortify<\/strong><\/h2>\n\n\n
\/\/ config\/fortify.php<\/span>\nuse<\/span> Laravel<\/span>\\Fortify<\/span>\\Features<\/span>;\n\nreturn<\/span> [\n    \/\/ ...<\/span>\n    'features'<\/span> => [\n        Features::registration(),\n        Features::resetPasswords(),\n        Features::emailVerification(),\n        Features::twoFactorAuthentication([\n            'confirmPassword'<\/span> => true<\/span>,\n        ]),\n    ],\n];<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Enabling Features::twoFactorAuthentication()<\/code> activates Fortify\u2019s 2FA endpoints: enabling\/disabling 2FA, generating recovery codes, and challenging users during login when 2FA is active.<\/p>\n\n\n
\/\/ app\/Providers\/FortifyServiceProvider.php<\/span>\nnamespace<\/span> App<\/span>\\Providers<\/span>;\n\nuse<\/span> Illuminate<\/span>\\Support<\/span>\\ServiceProvider<\/span>;\nuse<\/span> Laravel<\/span>\\Fortify<\/span>\\Fortify<\/span>;\n\nclass<\/span> FortifyServiceProvider<\/span> extends<\/span> ServiceProvider<\/span>\n<\/span>{\n    public<\/span> function<\/span> boot<\/span>()<\/span>: void<\/span>\n    <\/span>{\n        \/\/ Point Fortify to your custom Blade views:<\/span>\n        Fortify::loginView(fn() => view('auth.login'<\/span>)); \/\/ your existing login<\/span>\n        Fortify::twoFactorChallengeView(fn() => view('auth.two-factor-challenge'<\/span>));\n        \/\/ You can set other views (register, reset, etc.) as needed.<\/span>\n    }\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Fortify is \u201cheadless\u201d, so you must provide the login and two-factor challenge views. We will create a minimal set of views next.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
Profile UI: Enable \/ Disable 2FA + Show QR & Recovery Codes<\/strong><\/h2>\n\n\n\n
Fortify exposes signed-in endpoints for enabling\/disabling 2FA and regenerating recovery codes. Here\u2019s a simple Blade \u201cProfile Security\u201d section to manage 2FA on the frontend.<\/p>\n\n\n
<!-- resources\/views\/profile\/security.blade.php -->\n@extends('layouts.app'<\/span>)\n\n@section('content'<\/span>)\n  <h2>Two-Factor Authentication<\/h2>\n\n  @if<\/span> (! auth()->user()->two_factor_secret)\n    <form method=\"POST\"<\/span> action=\"\/user\/two-factor-authentication\"<\/span>>\n      @csrf\n      <button type=\"submit\"<\/span>>Enable 2<\/span>FA<\/button>\n    <\/form>\n  @else<\/span>\n    <p>2<\/span>FA is enabled on your account.<\/p>\n\n    <h3>Scan this QR code in your authenticator app<\/h3>\n    {!! auth()->user()->twoFactorQrCodeSvg() !!}\n\n    <h3 class<\/span>=\"mt<\/span>-3\">Recovery<\/span> Codes<\/span><\/h3<\/span>>\n    <ul<\/span>>\n      @foreach<\/span> (auth<\/span>()->user<\/span>()->recoveryCodes<\/span>() as<\/span> $code<\/span>)\n        <li<\/span>><code<\/span>><\/span>{{ $code }}<\/code><\/li>\n      @endforeach<\/span>\n    <\/ul>\n\n    <form method=\"POST\"<\/span> action=\"\/user\/two-factor-recovery-codes\"<\/span>>\n      @csrf\n      <button type=\"submit\"<\/span>>Regenerate Recovery Codes<\/button>\n    <\/form>\n\n    <form method=\"POST\"<\/span> action=\"\/user\/two-factor-authentication\"<\/span>>\n      @csrf\n      @method('DELETE'<\/span>)\n      <button type=\"submit\"<\/span> class<\/span>=\"mt<\/span>-3\">Disable<\/span> 2FA<\/span><\/button<\/span>>\n    <\/form<\/span>>\n  @endif<\/span>\n@endsection<\/span><\/span><\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
When 2FA is disabled, the form posts to \/user\/two-factor-authentication<\/code> to enable it. Once enabled, users see a QR SVG (scan with Google Authenticator, 1Password, Authy, etc.) and recovery codes. They can regenerate codes or disable 2FA via the provided forms.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
Two-Factor Challenge View (Login Step)<\/strong><\/h2>\n\n\n\n
After a successful password login for a user with 2FA enabled, Fortify redirects to a challenge page to enter the TOTP code or a recovery code. Create this Blade view and wire it in your FortifyServiceProvider<\/code> as shown earlier.<\/p>\n\n\n
<!-- resources\/views\/auth\/two-factor-challenge.blade.php -->\n@extends('layouts.guest'<\/span>)\n\n@section('content'<\/span>)\n  <h1>Two-Factor Challenge<\/h1>\n\n  <form method=\"POST\"<\/span> action=\"\/two-factor-challenge\"<\/span>>\n    @csrf\n\n    <div>\n      <label>Authentication Code<\/label>\n      <input type=\"text\"<\/span> name=\"code\"<\/span> inputmode=\"numeric\"<\/span> autocomplete=\"one-time-code\"<\/span>>\n    <\/div>\n\n    <p>Or<\/span> use<\/span> a<\/span> recovery<\/span> code<\/span>:<\/p<\/span>>\n\n    <div<\/span>>\n      <label<\/span>>Recovery<\/span> Code<\/span><\/label<\/span>>\n      <input<\/span> type<\/span>=\"text<\/span>\" name<\/span>=\"recovery_code<\/span>\">\n    <\/div<\/span>>\n\n    <button<\/span> type<\/span>=\"submit<\/span>\">Verify<\/span><\/button<\/span>>\n\n    @error<\/span>('code<\/span>') <p<\/span> class<\/span>=\"text<\/span>-danger<\/span>\">{{ $message<\/span> }}<\/p<\/span>> @enderror<\/span>\n    @error<\/span>('recovery_code<\/span>') <p<\/span> class<\/span>=\"text<\/span>-danger<\/span>\">{{ $message<\/span> }}<\/p<\/span>> @enderror<\/span>\n  <\/form<\/span>>\n@endsection<\/span><\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Posting to \/two-factor-challenge<\/code> tells Fortify to validate either the 6-digit code from the authenticator app or a recovery code, completing the login flow.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
Useful Events: Email Users When 2FA Changes<\/strong><\/h2>\n\n\n\n
Fortify fires events when users enable\/disable 2FA or regenerate recovery codes. You can listen to these and notify users for security awareness.<\/p>\n\n\n
\/\/ app\/Providers\/EventServiceProvider.php<\/span>\nprotected<\/span> $listen = [\n    \\Laravel\\Fortify\\Events\\TwoFactorAuthenticationEnabled::class => [\n        \\App\\Listeners\\SendTwoFactorEnabledNotification::class,\n    ],\n    \\Laravel\\Fortify\\Events\\TwoFactorAuthenticationDisabled::class => [\n        \\App\\Listeners\\SendTwoFactorDisabledNotification::class,\n    ],\n    \\Laravel\\Fortify\\Events\\RecoveryCodesGenerated::class => [\n        \\App\\Listeners\\SendRecoveryCodesRegeneratedNotification::class,\n    ],\n];<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Registering listeners lets you send mail, Slack\/Log notifications, or audit events whenever 2FA settings change.<\/p>\n\n\n
\/\/ app\/Listeners\/SendTwoFactorEnabledNotification.php<\/span>\nnamespace<\/span> App<\/span>\\Listeners<\/span>;\n\nuse<\/span> Illuminate<\/span>\\Support<\/span>\\Facades<\/span>\\Mail<\/span>;\nuse<\/span> Laravel<\/span>\\Fortify<\/span>\\Events<\/span>\\TwoFactorAuthenticationEnabled<\/span>;\n\nclass<\/span> SendTwoFactorEnabledNotification<\/span>\n<\/span>{\n    public<\/span> function<\/span> handle<\/span>(TwoFactorAuthenticationEnabled $event)<\/span>: void<\/span>\n    <\/span>{\n        $user = $event->user;\n        Mail::raw('Two-Factor Authentication was enabled on your account.'<\/span>, function<\/span> ($m)<\/span> use<\/span> ($user)<\/span> <\/span>{\n            $m->to($user->email)->subject('2FA Enabled'<\/span>);\n        });\n    }\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
This simple listener sends an email whenever a user enables 2FA. You can create similar listeners for disabled and regenerated codes to keep users informed.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
Controller Integration: Protect Critical Actions with Password\/2FA<\/strong><\/h2>\n\n\n\n
Even with 2FA enabled, you might want to require recent password confirmation (and therefore 2FA at login) before sensitive actions (like deleting an account). Fortify ships a password confirmation route you can require via middleware.<\/p>\n\n\n
\/\/ routes\/web.php<\/span>\nRoute::middleware(['auth'<\/span>, 'password.confirm'<\/span>])->group(function<\/span> ()<\/span> <\/span>{\n    Route::delete('\/account'<\/span>, [\\App\\Http\\Controllers\\AccountController::class, 'destroy'<\/span>])\n        ->name('account.destroy'<\/span>);\n});<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Using password.confirm<\/code> ensures the user recently re-entered their password (and has passed 2FA on login). You can also build a custom flow to ask for a fresh TOTP if you prefer a second check before a destructive action.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
Feature Test: Happy Path for 2FA Challenge<\/strong><\/h2>\n\n\n\n
This example shows how to simulate a user with 2FA enabled and verify that the two-factor challenge gate works. In practice, you can stub the verification logic or seed a valid TOTP using a known secret.<\/p>\n\n\n
\/\/ tests\/Feature\/TwoFactorLoginTest.php<\/span>\nnamespace<\/span> Tests<\/span>\\Feature<\/span>;\n\nuse<\/span> Tests<\/span>\\TestCase<\/span>;\nuse<\/span> App<\/span>\\Models<\/span>\\User<\/span>;\nuse<\/span> Illuminate<\/span>\\Foundation<\/span>\\Testing<\/span>\\RefreshDatabase<\/span>;\n\nclass<\/span> TwoFactorLoginTest<\/span> extends<\/span> TestCase<\/span>\n<\/span>{\n    use<\/span> RefreshDatabase<\/span>;\n\n    public<\/span> function<\/span> test_user_with_2fa_is_redirected_to_challenge<\/span>()<\/span>: void<\/span>\n    <\/span>{\n        $user = User::factory()->create([\n            \/\/ Pretend 2FA is enabled by seeding secret\/recovery fields:<\/span>\n            'two_factor_secret'<\/span> => encrypt('TESTSECRET'<\/span>),\n            'two_factor_recovery_codes'<\/span> => encrypt(json_encode(['recovery-code-1'<\/span>])),\n        ]);\n\n        \/\/ First step: password login (simulate posting valid credentials)<\/span>\n        $response = $this<\/span>->post('\/login'<\/span>, [\n            'email'<\/span> => $user->email,\n            'password'<\/span> => 'password'<\/span>, \/\/ matches default factory<\/span>\n        ]);\n\n        $response->assertRedirect('\/two-factor-challenge'<\/span>);\n\n        \/\/ Second step: submit a recovery code (bypassing TOTP for test)<\/span>\n        $challenge = $this<\/span>->post('\/two-factor-challenge'<\/span>, [\n            'recovery_code'<\/span> => 'recovery-code-1'<\/span>,\n        ]);\n\n        $challenge->assertRedirect('\/home'<\/span>); \/\/ or your intended location<\/span>\n        $this<\/span>->assertAuthenticatedAs($user);\n    }\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
The test verifies that a user with 2FA enabled is redirected to the challenge after password login, and that providing a valid recovery code authenticates them fully.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
Troubleshooting & Notes<\/strong><\/h2>\n\n\n\n