README

Protect user accounts with Two-Factor Authentication. Send 2FA verification codes for user via E-mail or SMS provider.

The package is helpful if you don't use Jetstream but need 2FA.

All classes are extendable, so you can extend and override everything and customize and adjust it to the project. There in no certain conception or implementation of 2FA. This package provides only a basic set of useful classes and methods, so you can implement 2FA how you want in way you want

Features:

Customiation: package includes a set of helpful stuff using for 2FA verification. You can implement them how you want and customize everything. Every class can be extended and overridden
Resent 2FA code: once per minute
Flexible config
Every code is valid for X minutes (config('2fa.user_code_valid_time')). If user use "Resend" function and recive N codes - every code is valid for X minutes

Requirements

Laravel 8.x to 9.x
PHP >= 8.0

Laravel and PHP support

Laravel version	PHP version	Release	Installation
10.x	PHP >=8.1	WIP	`composer require assghard/laravel-2fa`
8.x to 9.X	PHP >=8.0	0.1.2	`composer require assghard/laravel-2fa:0.1.2`

Package hasn't been tested on older Laravel versions

Installation

Installation and usage

Install latest release: run composer require assghard/laravel-2fa
- To install older version run: composer require assghard/laravel-2fa:VERSION
Add provider in config -> app.php providers section:

'providers' => [
    TwoFactorVerificationServiceProvider::class,
]

Publish vendor: php artisan vendor:publish --provider="Assghard\Laravel2fa\TwoFactorVerificationServiceProvider" That command will add a few files to your project:

config/2fa.php #2FA config

# migrations
migrations/create_user_2fa_codes_table.php
migrations/add_phone_number_field_to_users_table.php

# translations: add or delete languages you don't need
lang/en/2fa.php
lang/pl/2fa.php

Remenber abount adding variables to .env nad .env.example files

# To enable 2FA for users
2FA_ENABLED=true

# uncomment if you are going to use sending 2FA SMS codes
# SMS_API_TOKEN=
# SMS_API_NAME_FORM=

Run command: php artisan migrate
Add stuff to your User model:

/*
 * =========================================
 * Basic usage
 * =========================================
 */

use Assghard\Laravel2fa\Traits\UserTwoFactorVerificationTrait; # Add trait in use section
use Assghard\Laravel2fa\Enums\TwoFactorVerificationMethodsEnum; # available 2FA methods Enum
...

class User extends Authenticatable implements MustVerifyEmail
{
    use UserTwoFactorVerificationTrait; // Use trait for 2FA
    ...

    /**
     * The attributes that are mass assignable.
     *
     * @var array<int, string>
     */
    protected $fillable = [ # Add fillable fields
        ...
        'phone_number', # only if you are going to send 2FA codes via SMS message
    ];

Send a 2FA code after user is successfully logged in.

App\Http\Controllers\Auth\AuthenticatedSessionController

use Assghard\Laravel2fa\Services\TwoFactorVerificationService;
use Assghard\Laravel2fa\Enums\TwoFactorVerificationMethodsEnum;
...
class AuthenticatedSessionController extends Controller
{
    ...

    $sent = (new TwoFactorVerificationService())->sendUserTwoFactorVerificationCode($user, $verificationMethodFromEnum);
    dd($sent);
    // And do everything you want after sending code

You will need a Controller: php artisan make:controller Auth\TwoFactroVerificationAuthController
Also you will need x3 routes for 2FA verification. Add them to Laravel auth.php routes.

    Route::middleware('auth')->group(function () {
        ...
        Route::group(['prefix' => '2fa'], function () {
            Route::get('verify', [TwoFactroVerificationAuthController::class, 'verify'])->name('2fa.verify');
            Route::post('verify', [TwoFactroVerificationAuthController::class, 'confirm'])->name('2fa.verify.confirm')->middleware('throttle:2fa_verify_confirm');
            Route::get('resend', [TwoFactroVerificationAuthController::class, 'resend'])->name('2fa.resend-code');
    });

Make a new 2fa_verify_confirm throttle in project RouteServiceProvider

    // 2fa_verify_confirm is a name of throttle and middleware
    RateLimiter::for('2fa_verify_confirm', function (Request $request) {
        return Limit::perMinute(5)->by($request->user()?->id ?: $request->ip());
    });

Probably, you will need a middleware to check if code is verified.

Run command php artisan make:middleware User2faCodeVerified

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;

class User2faCodeVerified
{
    /**
     * Handle an incoming request.
     *
     * @param  \Illuminate\Http\Request  $request
     * @param  \Closure(\Illuminate\Http\Request): (\Illuminate\Http\Response|\Illuminate\Http\RedirectResponse)  $next
     * @return \Illuminate\Http\Response|\Illuminate\Http\RedirectResponse
     */
    public function handle(Request $request, Closure $next)
    {
        // And do something like this or not :)
        // Database, session or other approach - the choice is yours

        $user = auth()->user();
        if ($user->two_factor_verification_codes()->count() > 0) {
            return redirect()->route('2fa.verify');
        }

If you are going to assign 2FA method to user and user (or Admin) can change the method (in this case remember to create a migration for tfa_method field):

/*
 * =========================================
 * NOT Basic usage (Example of customization)
 * =========================================
 */

    /**
     * The attributes that should be hidden for serialization.
     *
     * @var array<int, string>
     */
    protected $hidden = [
        ...
        'tfa_method' // 2FA method
    ];

    /**
     * The attributes that should be cast.
     *
     * @var array<string, string>
     */
    protected $casts = [
        ...
        'tfa_method' => TwoFactorVerificationMethodsEnum::class, // leverage enums for 2FA method casting
    ];

Package components

Migration stubs
Translations
Model
Enum
Email and SMS providers
Traits
Notification providers
Flexible config

    /**
     * Enable 2FA for Users. After enabling this feature 2FA will be required
     */
    'enabled' => env('2FA_ENABLED', false),

    /**
     * Default 2FA method
     * TwoFactorVerificationMethodsEnum::cases()
     */
    'default_method' => TwoFactorVerificationMethodsEnum::Email,

    /**
     * After successful login all user codes are deleting, so user will have limit reseted
     */
    'daily_user_codes_limit' => 25,

    /**
     * Single code valid time in minutes.
     * expires_at = now() + user_code_valid_time
     */
    'user_code_valid_time' => 10,

    'code' => [
        /**
         * Default 2FA code length
         */
        'length' => 6,
    
        /**
         * Default 2FA code length
         */
        'use_letters' => false,
    ],

    /**
     * SMS API config
     */
    'sms' => [
        /**
         * API token from https://www.smsapi.com/en
         */
        'api_token' => env('SMS_API_TOKEN', null),

        /**
         * Sender name
         */
        'name_from' => env('SMS_API_NAME_FORM', null),
    ],

TODO list:

Testing
Refactoring
Testing
Add user IP address field to user_2fa_codes table? Make code is valid only for certain IP address?

Bugs and suggestions

If you find a bug, please open an issue or fork this project and make Pull request

License

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

assghard / laravel-2fa

Maintainers

Details