New

Just launched: Vueblocks, a brand-new search engine for Vue packages! Explore Vueblocks →

sinemacula/laravel-mfa

Driver-based multi-factor authentication (TOTP, email, SMS, passkeys and recovery codes) for Laravel 12 and 13.
1,390
Install
composer require sinemacula/laravel-mfa:dev-master
PHP:^8.3
License:Apache-2.0
Last Updated:Nov 10, 2026
Links: GitHub  ·  Packagist
Maintainer: sinemacula

Laravel MFA

Latest Stable Version PHP Version Laravel Version Build Status Quality Gates Maintainability Code Coverage Total Downloads License

Driver-based multi-factor authentication for Laravel. Adds factors (TOTP, email codes, SMS codes and passkeys), recovery codes, step-up verification and a route gate to any guard, and says what a session's proofs add up to on the scale NIST SP 800-63B-4 defines.

Works alone behind any Laravel guard and any Authenticatable model, or with sinemacula/laravel-authentication through adapters you or sinemacula/laravel-iam bind: this package references no class of another. Routes, controllers and user interfaces stay yours.

Core Concept

Concept What it is
Factor One enrolled means of proving a further factor: an authenticator app, a phone, an email address or a passkey.
Proof One verified authentication event on a session, with its time, its binding and the properties actually observed.
Requirement What a session must prove: an additional verification, multifactor authentication, a level, phishing resistance.
Application The app being signed into, by default the guard's name. It chooses the types it accepts, its requirement and limits.
Recovery code One code of a single-use set for a person who has lost their factors. A fallback, never a factor.
Assurance level What a combination of proofs supports: aal1, aal2, aal3, or unclassified when the evidence supports none.

Factors belong to the identity and are the same in every application; proofs belong to one sign-in. Everything the package decides about a session is worked out from its proofs, never from a single "verified at" time.

Installation

composer require sinemacula/laravel-mfa

Configuration

Publish the config and the migrations, then migrate:

php artisan vendor:publish --tag=mfa-config
php artisan vendor:publish --tag=mfa-migrations
php artisan migrate

An application enables nothing until it says so. Give each one a block in config/mfa.php, under the name of its guard, naming the factor types it accepts, when it requires a factor and the first factor its guard signs people in with:

'applications' => [
    'web' => [
        'types'          => ['totp', 'email'],
        'requirement'    => 'enrolled',
        'recovery_codes' => ['enabled' => true],
        'first_factor'   => ['method' => 'password', 'channel' => 'password'],
    ],
],

An application that enables email or sms binds a sender to deliver its codes:

use SineMacula\Laravel\Mfa\Codes\MailEmailSender;
use SineMacula\Laravel\Mfa\Contracts\EmailSender;

$this->app->bind(EmailSender::class, MailEmailSender::class);

Every setting has a production-safe default and enforced bounds. The package checks the whole configuration when it boots, and php artisan mfa:check reports every problem for a deploy pipeline. TOTP secrets are encrypted with APP_KEY, so keep an old key in APP_PREVIOUS_KEYS when you rotate it (see Rotating the application key), and every package table lives on one connection, storage.connection (see Storage).

See Installation for senders and the ways of running, and Configuration for every option.

Usage

Give your identity model the contract and the trait:

use Illuminate\Foundation\Auth\User;
use SineMacula\Laravel\Mfa\Concerns\HasFactors;
use SineMacula\Laravel\Mfa\Contracts\MultiFactorAuthenticatable;

class AppUser extends User implements MultiFactorAuthenticatable
{
    use HasFactors;
}

Verify on routes of your own, through the Mfa facade:

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
use SineMacula\Laravel\Mfa\Context\CallerContext;
use SineMacula\Laravel\Mfa\Enums\Purpose;
use SineMacula\Laravel\Mfa\Facades\Mfa;
use SineMacula\Laravel\Mfa\Verification\Submission;

Route::middleware(['web', 'auth', 'mfa.exempt'])->post('/mfa/verify', function (Request $request) {
    $result = Mfa::verify(CallerContext::fromRequest($request), Submission::factor(
        $request->string('factor')->toString(),
        $request->string('code')->toString(),
    ), Purpose::SIGN_IN);

    return $result->isFailed()
        ? response()->json(['reason' => $result->reason->value], 422)
        : response()->noContent();
});

Every helper that acts for a person takes the caller first, read from the request once with CallerContext::fromRequest() or built from plain values away from one (see The caller). This form is for TOTP. Email and SMS factors use Mfa::sendCode() and then Submission::challenge(), and a step-up leaves the purpose out (see Verification).

Gate the rest with the middleware, asking for more where a route needs it:

Route::middleware('mfa')->group(function () {
    Route::get('/dashboard', DashboardController::class);

    Route::middleware('mfa:level=aal2')->get('/billing', BillingController::class);
    Route::middleware('mfa:operation=account.delete')->delete('/account', DeleteAccountController::class);
});

A request that falls short raises InsufficientAuthenticationException, a 401 carrying the requirement and the factors on offer as masked summaries (see Route middleware).

Before you ship, read CSRF protection for cookie-authenticated routes that change factors or recovery codes, Identity models for machines and inactive identities, and Secrets for sending what is shown once. To claim an assurance level, follow the NIST SP 800-63B-4 compliance profile.

Guides

Guide Covers
Installation Publishing, the first application, senders, and running alone or with the suite
Identity models The contract and trait, machines, inactive identities, deleting an identity
Configuration Every key, its default and its bounds, storage, and the configuration check
Helpers Every Mfa:: helper, who it serves, how it refuses, and binding a factor to a route
Enrolment Starting and confirming a factor, the grant, replacing a factor, labels
Verification Mfa::verify(), what a code is bound to, offers, results, failure reasons, completion
Recovery codes Generating, redeeming and removing a set, and what it costs
Attempts and lockouts Every counter, what resets it, the failure ceiling and limiting the endpoint
Requirements and step-up What a sign-in must prove, per-operation freshness, and the contracts behind them
Route middleware mfa and mfa.exempt, who is refused, answering, CSRF protection, the authentication context
Recorded proofs Reading proofs, sign-ins, custom and stateless guards, invalidating proofs
Proofs, assurance and requirements The values, the combination policy, the default classification and the stable names
Compliance What an application must also configure to claim a NIST SP 800-63B-4 level
Factor lifecycle Listing, removing, resetting, unlocking and pruning
Secrets What is shown once, sending it, redaction, failed queries and key rotation
Events Every event, its payload and its context
Localisation Every message, translating it, and what is not translated
Operations Octane, queue workers, read replicas, database failure and the cache
Testing Fake senders, the current TOTP code, acting as a verified identity
Extending Custom drivers and models, every seam and its default, the seams with an authentication layer

The security and lifecycle contracts behind them, for maintainers and reviewers, are in docs/design.

Requirements

  • PHP ^8.3 (extensions: mbstring)
  • Laravel ^12.40 || ^13.3

Testing

composer test               # all suites in parallel (Paratest)
composer test:coverage      # all suites with clover coverage
composer test:unit          # unit suite only
composer test:feature       # feature suite only
composer test:integration   # integration suite only
composer test:performance   # performance budget suite (serial)
composer test:mutation      # scoped mutation gate
composer test:mutation:full # full mutation suite (no thresholds)
composer bench              # PHPBench hot-path benchmarks
composer check              # static analysis + style
composer format             # format the codebase
composer smells             # advisory code smells (duplication, complexity)

Changelog

See CHANGELOG.md for a list of notable changes.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for guidelines on branching, commits, code quality, and pull requests.

Security

If you discover a security vulnerability, please report it responsibly. See SECURITY.md for the disclosure policy and contact details.

License

Licensed under the Apache License, Version 2.0.

Related Packages

sicaboy/laravel-mfa

A Laravel package of Multi-factor Authentication (MFA/2FA) with a middleware.

1,321 11
laragear/two-factor

On-premises 2FA Authentication for out-of-the-box.

1,368,631 343
gabrielesbaiz/nova-two-factor

Two-factor authentication for Laravel Nova: authenticator apps, passkeys, email...

19,822 2
aymakan/laravel-mfa

API-only Multi-Factor Authentication enforcement for Laravel (TOTP, middleware-d...

2,176 0
jeffersongoncalves/filament-multifactor-passkeys

Filament 5 multi-factor authentication via WebAuthn passkeys, powered by spatie/...

7,024 8