README

Implementing Email OTP and Authenticator App 2FA logic with Trusted Devices support.

Features

Installation

You can install the package via composer:

composer require mix-code/filament-multi-2fa

Install plugin configs and migrations:

php artisan filament-multi-2fa:install

Optionally, you can publish the lang files with:

php artisan vendor:publish --tag="filament-multi-2fa-translations"

Optionally, you can publish the views using:

php artisan vendor:publish --tag="filament-multi-2fa-views"

Usage

1️⃣ Register the plugin in your Filament Panel

In your PanelProvider (e.g., AdminPanelProvider):

public function panel(Panel $panel): Panel
{
    return $panel
        // other panel setup...
        ->plugins([
            // ...
            \MixCode\FilamentMulti2fa\FilamentMulti2faPlugin::make(),
        ]);
}

Force 2FA setup:

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            \MixCode\FilamentMulti2fa\FilamentMulti2faPlugin::make()
                ->forceSetup2fa(),
        ]);
}

2️⃣ Configure User Model

In your User model, use the UsingTwoFA trait, guarded attributes and casts:

use MixCode\FilamentMulti2fa\Traits\UsingTwoFA;
use MixCode\FilamentMulti2fa\Enums\TwoFactorAuthType;

class User extends Authenticatable
{
    use UsingTwoFA;

    protected $guarded = [
        'two_factor_type',
        'two_factor_secret',
        'two_factor_recovery_codes',
        'two_factor_sent_at',
        'two_factor_expires_at',
        'two_factor_confirmed_at',
    ];

    protected $casts = [
        'two_factor_type' => TwoFactorAuthType::class,
        'two_factor_sent_at' => 'datetime',
        'two_factor_expires_at' => 'datetime',
        'two_factor_confirmed_at' => 'datetime',
    ];

    // ...
}

You can also configure redirection after OTP verification by overriding redirectAfterVerifyUrl:

public function redirectAfterVerifyUrl(): ?string
{
    return route('home');
}

To list user trusted devices:

$user->trustedDevices();

3️⃣ Features Automatically Handled by the Plugin:

🛡️ 2FA Setup Page (users can select Email OTP or Authenticator App)
🔑 OTP Verification Page to protect access based on trusted device and 2FA status
🖥 Trusted Device Middleware to check trusted device cookies and enforce OTP verification
🔐 Adds a shortcut in the user menu to access the 2FA setup page

4️⃣ Automatic Logout Handling

When users log out, the plugin clears their two_factor_confirmed_at column automatically:

Event::listen(Logout::class, function ($event) {
    $user = $event->user;

    if ($user) {
        $user->two_factor_confirmed_at = null;
        $user->save();
    }
});

5️⃣ Customize settings from the config file

return [

    /*
    |--------------------------------------------------------------------------
    | Models Configuration
    |--------------------------------------------------------------------------
    |
    | Define the models used by the package here. These models will be used
    | for users and trusted device storage.
    |
    */

    'user_model' => \App\Models\User::class,

    'trust_device_model' => \MixCode\FilamentMulti2fa\Models\TrustDevice::class,

    /*
    |--------------------------------------------------------------------------
    | Notifications
    |--------------------------------------------------------------------------
    |
    | Specify the notification class responsible for sending the OTP code
    | to the user.
    |
    */

    'otp_notification_class' => \MixCode\FilamentMulti2fa\Notifications\TwoFactorCodeNotification::class,

    /*
    |--------------------------------------------------------------------------
    | QR Code Rendering Backend
    |--------------------------------------------------------------------------
    |
    | Choose the QR code rendering service to generate the QR Code for TOTP.
    |
    | Supported Services:
    |
    | 1. BaconQrCode (default):
    |    - Renders PNG (inline or file)
    |    - Requires the Imagick PHP extension (depending on backend)
    |    - Can render SVG with custom setup, but PNG is common default
    |
    | 2. chillerlan/php-qrcode:
    |    - Outputs base64-encoded PNG by default
    |    - Supports SVG rendering via OUTPUT_MARKUP_SVG
    |    - Does NOT require Imagick or GD by default for PNG base64
    |    - Other formats (PNG file, SVG file) may require GD/Imagick if saved to disk
    |
    */

    // Default to BaconQrCode
    'qr_code_backend_service' => \PragmaRX\Google2FAQRCode\QRCode\Bacon::class,

    // To use chillerlan/php-qrcode (SVG by default), uncomment below:
    // 'qr_code_backend_service' => \PragmaRX\Google2FAQRCode\QRCode\Chillerlan::class,

    /*
    |--------------------------------------------------------------------------
    | OTP Settings
    |--------------------------------------------------------------------------
    |
    | OTP Specific Settings From the view of the notification to the resend remains.
    |
    */

    'otp_view' => 'filament-multi-2fa::emails.2fa.otp',

    'otp_resend_time_format' => '%i:%S', // 1:15

    'otp_resend_allowed_after_in_seconds' => 60 * 1, // 1 Minute

    'otp_expiration_in_seconds' => 60 * 10,   // 10 Minute

    /*
    |--------------------------------------------------------------------------
    | Trusted Device Settings
    |--------------------------------------------------------------------------
    |
    | Configure trusted device cookie settings, including cookie name,
    | lifespan in minutes, and cache settings to minimize DB hits.
    |
    */

    'trusted_device_cookie_name' => 'trusted_device',

    // Duration (in minutes) before a trusted device expires in the database
    'trusted_device_db_expiration' => 60 * 24 * 30, // 30 days

    // Duration (in minutes) before a trusted device cookie expires
    'trusted_device_cookie_lifespan' => 60 * 24 * 30, // 30 days

    // Duration (in minutes) to cache trusted device checks to reduce DB queries
    'trust_device_check_cache_lifespan' => 60 * 24 * 30, // 30 days

];

📝 Notes:

The plugin automatically injects the CheckTrustedDevice middleware to protect your Filament admin routes.
After OTP verification, users are redirected to the current panel’s dashboard.

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.

mix-code / filament-multi-2fa

Maintainers

Details