README

Introduction

A powerful and flexible Laravel package that provides Multi-factor Authentication (MFA) / Two-factor Authentication (2FA) middleware to secure your Laravel applications. This package was originally part of sicaboy/laravel-security and has been moved to this dedicated repository.

Features

✅ Easy Integration - Simple middleware-based implementation
✅ Email-based MFA - Secure code delivery via email
✅ Multiple Auth Guards - Support for different authentication contexts (user, admin, etc.)
✅ Configurable - Flexible configuration options
✅ Queue Support - Background email sending with Laravel queues
✅ Cache-based - Efficient code storage and verification tracking
✅ Customizable Views - Override templates to match your design
✅ Laravel 5.7+ Support - Compatible with modern Laravel versions

Note

🚀 Advertisement: Don't Want to Build Authentication From Scratch?

Save weeks of development time with Users.au - a complete authentication solution for Laravel!

Why Choose Users.au?

🎯 Ready-to-use Authentication - Complete user management system
🔐 Built-in MFA/2FA - No need for additional packages
⚡ Laravel Integration - Seamless setup with your existing Laravel app
🆓 Free to Start - Get started without any upfront costs
🛠️ Developer-friendly - Multiple integration options

Get Started in Minutes:

Option 1: Laravel Starter Kit (Fastest)

git clone https://github.com/Users-au/laravel-starter-kit.git
cd laravel-starter-kit
composer install

Option 2: Add to Existing Laravel App

composer require users-au/laravel-client

Option 3: Socialite Integration

composer require users-au/socialite-provider

Resources:

🌐 Website: https://www.users.au
📦 Laravel Starter Kit: https://github.com/Users-au/laravel-starter-kit
🔧 Laravel Package: https://github.com/Users-au/laravel-client
🔑 Socialite Provider: https://github.com/Users-au/socialite-provider

Skip the complexity of building authentication from scratch and focus on what makes your app unique!

Installation

Requirements

PHP 7.1+ or 8.0+
Laravel 5.7+
Composer

Install via Composer

composer require sicaboy/laravel-mfa

Publish Configuration and Views

php artisan vendor:publish --provider="Sicaboy\LaravelMFA\LaravelMFAServiceProvider"

This will publish:

Configuration file: config/laravel-mfa.php
View templates: resources/views/vendor/laravel-mfa/

Service Provider Registration (Laravel < 5.5)

If you're using Laravel < 5.5, manually register the service provider in config/app.php:

'providers' => [
    // ...
    Sicaboy\LaravelMFA\LaravelMFAServiceProvider::class,
],

Usage

Basic Usage

Protect your routes by applying the mfa middleware:

// Protect individual routes
Route::get('/dashboard', 'DashboardController@index')->middleware('mfa');

// Protect route groups
Route::middleware(['mfa'])->group(function () {
    Route::get('/admin', 'AdminController@index');
    Route::get('/profile', 'ProfileController@show');
});

Multiple Authentication Guards

If you use multiple authentication guards (e.g., separate user and admin authentication), specify the guard group:

// For admin routes
Route::middleware(['mfa:admin'])->group(function () {
    Route::get('/admin/dashboard', 'Admin\DashboardController@index');
});

Configure the corresponding group in config/laravel-mfa.php:

return [
    'default' => [
        // Default configuration...
    ],
    'group' => [
        'admin' => [ // Example, when using middleware 'mfa:admin'. Attributes not mentioned will be inherit from `default` above
            'login_route' => 'admin.login',
            'auth_user_closure' => function() {
                return \Encore\Admin\Facades\Admin::user();
            },
        ],
        'other_name' => [ // Middleware 'mfa:other_name'
            ...
        ]
    ],
];

Configuration Options

Email Configuration

Configure email settings in config/laravel-mfa.php:

'email' => [
    'queue' => true, // Enable queue for background sending
    'template' => 'laravel-mfa::emails.authentication-code',
    'subject' => 'Your Authentication Code',
],

Code Expiration

Set how long verification codes remain valid:

'code_expire_after_minutes' => 10, // Default: 10 minutes

Queue Configuration

For applications with queue workers running, enable background email sending:

return [
    'default' => [
        'email' => [
            'queue' => true, // Enable queue processing
        ]
    ]
];

Make sure your queue worker is running:

php artisan queue:work

API Responses

The middleware provides JSON responses for API requests:

403 - User not authenticated
423 - MFA verification required

{
    "error": "MFA Required",
    "url": "/mfa/generate?group=default"
}

Testing

Run the test suite:

composer test

Or run PHPUnit directly:

./vendor/bin/phpunit

Security Considerations

Codes expire after the configured time limit (default: 10 minutes)
Verification status is cached to prevent replay attacks
Email delivery can be queued for better performance
Multiple authentication contexts are supported

Roadmap

✅ Email-based MFA
🔄 SMS-based MFA
🔄 TOTP/Authenticator app support
🔄 User-specific MFA settings
🔄 Backup codes

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

Development Setup

Clone the repository:

git clone https://github.com/sicaboy/laravel-mfa.git
cd laravel-mfa

Install dependencies:

composer install

Run tests:

composer test

Running Tests

# Run all tests
composer test

# Run tests with coverage
./vendor/bin/phpunit --coverage-html build/coverage

# Run specific test file
./vendor/bin/phpunit tests/Unit/MFAHelperTest.php

# Run specific test method
./vendor/bin/phpunit --filter testGetConfigByGroupReturnsGroupConfig

Changelog

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

License

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

Support

Issues: GitHub Issues
Documentation: This README and inline code documentation
Email: slj@slj.me

sicaboy / laravel-mfa

Maintainers

Details