README

Adds Two Factor authentication to Filament Panels. Requires an app like Authy or Google Authenticator to generate Time-based One Time Pins every 60 seconds.

Installation

You can install the package via composer:

composer require visualbuilder/filament-2fa

You can publish and run the migrations with:

php artisan vendor:publish --tag="filament-2fa-migrations"
php artisan migrate

A Banner Seeder adds a configurable Setup 2FA banner shown to users who are not setup yet

php artisan vendor:publish --tag="filament-2fa-seeders"
php artisan db:seed --class=TwoFactorBannerSeeder

Publish the config files

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

This package extends the https://github.com/Laragear/TwoFactor

so you will see two new config files:-

config/two-factor.php
config/filament-2fa.php

Review the config files

Set preferences for safe devices and recovery codes.

    'safe_devices' => [
        'enabled' => true,
        'cookie' => '_2fa_remember',
        'max_devices' => 3,
        'expiration_days' => 14,
    ],

Note the Two-Factor Login Helper is not used, there is a custom login form which you can extend

Optionally, you can publish the views using

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

Usage

Minimal configuration required to enable 2FA on a panel.

Step 1:

Implement TwoFactorAuthenticatables on the authenticatable model

use Visualbuilder\Filament2fa\Contracts\TwoFactorAuthenticatable;
use Visualbuilder\Filament2fa\Traits\TwoFactorAuthentication;

class Admin extends Authenticatable implements FilamentUser, TwoFactorAuthenticatable
{
    use HasFactory, TwoFactorAuthentication;
}

Step 2:

Add TwoFactor Plugin on PanelServiceProvider

public function panel(Panel $panel): Panel
{
    return $panel
        ->default()
        ->id('admin')
        ->plugins([
            TwoFactorPlugin::make()
        ])
}

Step 3:

Add menu items where required. For all users Setup Two Factor Authentication link For Admins only Banner Manager pages

use Visualbuilder\Filament2fa\Filament\Pages\Login;

public function panel(Panel $panel): Panel
{
    return $panel
        ->default()
        ->id('admin')
        ->plugins([
            TwoFactorPlugin::make()
        ])
        ->login(Login::class)
        ->userMenuItems([
        /**
        * 2FA setup and manage link
        */
        MenuItem::make('two-factor')
                    ->url('/two-factor-authentication')
                    ->label('Two Factor Auth')
                    ->icon('heroicon-o-key')
                    ->sort(1),
                    
         /**
         * Banner manager
         * Ensure you limit access to who can change banners 
         */           
        MenuItem::make('two-factor-banner')
            ->url(config('filament-2fa.banner.navigation.url'))
            ->label(config('filament-2fa.banner.navigation.label'))
            ->icon(config('filament-2fa.banner.navigation.icon'))
            ->sort(2)
            ->visible(fn() => Filament::auth()->user()->hasRole(['Developer', 'Super Admin'],'web'))

Step 4:

Can enable or disable TwoFactor in filament-2fa.php config file

use Filament\Pages\SubNavigationPosition;
return [
    'defaultDateTimeDisplayFormat'  => 'd M Y H:i',

    'excluded_routes' => [
        'two-factor-authentication',
        'confirm-2fa',
        'logout',
    ],

    'login' => [
        'flashLoginCredentials' => false,
        'credential_key' => '_2fa_login',
        'confirm_totp_page_url' => 'confirm-2fa'
    ],

    'navigation' => [
        'visible_on_navbar' => true,
        'icon' => 'heroicon-o-key',
        'group' => 'Auth Security',
        'label' => 'Two Factor Auth',
        'cluster' => null,
        'sort_no' => 10,
        'subnav_position' => SubNavigationPosition::Top
    ],

    'auth_guards' => [
        'web' => [
            'enabled' => 'true', 
            'mandatory' => false
        ]
    ],

    'banner' => [        
        'auth_guards' => [
            'web' => [
                'can_manage' => true,
                'can_see_banner' => true,
            ]
        ],
        'navigation' => [
            'icon' => 'heroicon-m-megaphone',
            'label' => '2FA Banners',
            'url' => 'banner-manager'
        ],
        'excluded_routes' => [
            'two-factor-authentication',
            'confirm-2fa',
        ]
    ]
];

Middleware

1. RedirectIfTwoFactorNotActivated.php
2. SetRenderLocation.php

If the mandatory authentication guard user has not set up 2FA, they will be redirected to the two-factor authentication setup page by the RedirectIfTwoFactorNotActivated middleware.

The SetRenderLocation middleware will display a notification banner on a page to remind to enable 2FAThe SetRenderLocationmiddleware will display a notification banner on a page to remind users to enable 2FA.

2FA Notification Banner

In the configuration, if the auth guard is enabled to manage the banner, the user can create, edit, delete, and enable/disable the banner.

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.

visualbuilder / filament-2fa

Maintainers

Details