README

Two-Factor Authentication for Laravel

Native RFC 6238 TOTP two-factor authentication for Laravel: encrypted secrets, single-use recovery codes, replay protection and a built-in brute-force limiter, with no third-party crypto dependencies. It hands you the otpauth:// URI, so you render the QR code wherever suits your stack.

Installation

Requires PHP 8.4, Laravel 12 or 13.

composer require roundly-consulting/two-factor-for-laravel
php artisan vendor:publish --tag="two-factor-migrations"
php artisan migrate

The migration adds four nullable columns to your users table. If your accounts live in another table, set TWO_FACTOR_TABLE before migrating.

Usage

Prepare the user model:

use Illuminate\Foundation\Auth\User as Authenticatable;
use RoundlyConsulting\TwoFactor\Concerns\HasTwoFactorAuthentication;
use RoundlyConsulting\TwoFactor\Contracts\TwoFactorAuthenticatable;

final class User extends Authenticatable implements TwoFactorAuthenticatable
{
    use HasTwoFactorAuthentication;

    protected function casts(): array
    {
        return [...$this->twoFactorCasts()];
    }
}

Enrol, confirm with the first code, then challenge at login:

use RoundlyConsulting\TwoFactor\Facades\TwoFactor;

$setup = TwoFactor::for($user)->start(issuer: 'Acme');
$setup->provisioningUri;                          // otpauth://totp/Acme:… — render it as a QR code
$setup->recoveryCodes;                            // list<string> — show these once

TwoFactor::for($user)->confirm($code);            // the first authenticator code switches 2FA on

$result = TwoFactor::for($user)->attempt($code);  // TOTP (replay-safe) or a single-use recovery code
$result->verified;                                // bool
$result->method;                                  // TwoFactorMethod::Totp | ::RecoveryCode | null

TwoFactor::for($user)->status()->enabled;         // true

Documentation

The full documentation — configuration, every feature and its API, and testing — lives on our website: roundly-consulting.com/open-source/docs/two-factor-for-laravel

Release notes are in CHANGELOG.md. To contribute, see the contributing guide.

Support our work

This package is free and open source, built and maintained by Roundly Consulting. If it saves you time, please consider supporting our open-source work — a one-time donation, a monthly pledge on Patreon or a crypto donation helps fund maintenance, new features and new packages.

License

The MIT License (MIT). Please see LICENSE.md. Maintained by roundly-consulting.

roundly-consulting / two-factor-for-laravel

Package info

Security

Fund package maintenance!

Statistics