README

Protect sensitive routes or actions with a confirmation-screen and ask for the two-factor authentication code of a user. Users are not asked for a confirmation again for a given time period. (Similar to the Password Confirmation feature of Laravel.)

The package uses Laravel Fortify under the hood to confirm the two-factor authentication code.

Installation

You can install the package via composer:

composer require wnx/laravel-tfa-confirmation

You can publish the config file with:

php artisan vendor:publish --tag="tfa-confirmation-config"

This is the contents of the published config file:

<?php

use Wnx\TfaConfirmation\Http\Controllers\ConfirmTwoFactorAuthenticationCodeController;
use Wnx\TfaConfirmation\Http\Controllers\TwoFactorAuthenticationChallengeController;
use Wnx\TfaConfirmation\Http\Responses\DefaultJsonResponse;

return [
    /**
     * Enable or disable two-factor authentication confirmation.
     */
    'enabled' => env('TFA_CONFIRMATION_ENABLED', true),

    /**
     * The session key that is used to store the timestamp of the last time
     * the user confirmed their two-factor authentication code.
     */
    'session_key' => 'auth.two_factor_confirmed_at',

    /**
     * The amount of time in seconds the confirmation is valid.
     * Users will not be asked to enter their two-factor authentication code again for this amount of time.
     */
    'timeout' => env('TFA_CONFIRMATION_TIMEOUT', 60 * 60 * 24), // 24 hours

    /**
     * The view that should be returned when the user needs to confirm their two-factor authentication code.
     * You should publish the views to your application to customize the challenge view.
     */
    'challenge_view' => 'tfa-confirmation::challenge',

    /**
     * Controller used to show the two-factor authentication challenge view.
     */
    'challenge_controller' => TwoFactorAuthenticationChallengeController::class,

    /**
     * Controller used to confirm the two-factor authentication code entered by the user on the challenge view.
     * If you customize this controller, make sure to dispatch the `\Laravel\Fortify\Events\ValidTwoFactorAuthenticationCodeProvided` event.
     */
    'confirmation_controller' => ConfirmTwoFactorAuthenticationCodeController::class,

    /**
     * The response that should be returned when the user needs to confirm their
     * two-factor authentication code, but the request expects a JSON response.
     */
    'json_response' => DefaultJsonResponse::class,
];

The defaul challenge-view is not styled. We highly recommend you publish the views and customize them to your design.

php artisan vendor:publish --tag="tfa-confirmation-views"

Usage

To protect routes with a two-factor confirmation challenge add the \Wnx\TfaConfirmation\Http\Middleware\RequireTwoFactorAuthenticationConfirmation-middleware to your routes.

// routes/web.php

// Protect a single route
Route::get('/super-important-route', SuperImportantController::class)
    ->middleware([
        // Use Middleware directly
        \Wnx\TfaConfirmation\Http\Middleware\RequireTwoFactorAuthenticationConfirmation::class,

        // Use Middleware alias
        'require_twofactor_confirmation',
    ]);

// Protect a group of routes
Route::middleware([
    'auth:sanctum',
    'verified',
    \Wnx\TfaConfirmation\Http\Middleware\RequireTwoFactorAuthenticationConfirmation::class,
])->group(function () {
    // Routes that need to be protected by two factor authentication
});

Note

If a given user does not have two-factor authentication enabled, the middleware is bypassed and the user will not be asked to confirm their two-factor authentication code. If you want certain routes only to be available to users with two-factor authentication enabled, you have to write a custom middleware that checks this condition.

Note

The package listens to the Laravel\Fortify\Events\ValidTwoFactorAuthenticationCodeProvided event to store the timestamp of the last time the user confirmed their two-factor authentication code. This ensures that the user is not asked to confirm their two-factor authentication code right after logging in.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

wnx / laravel-tfa-confirmation

Maintainers

Details