Filament 2Fa Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require webbingbrasil/filament-2fa
   php artisan vendor:publish --tag="filament-2fa-migrations"
   php artisan migrate
   

   Ensure filament >= 2.10.40 is installed.

2. User Model Trait: Add \Webbingbrasil\FilamentTwoFactor\TwoFactorAuthenticatable to your User model.

3. Configure Filament Auth: Update config/filament.php:

   "auth" => [
       "pages" => [
           "login" => \Webbingbrasil\FilamentTwoFactor\Http\Livewire\Auth\Login::class,
       ],
   ],
   

4. First Use Case:

   • Test 2FA flow by logging in via Filament’s login page. The package handles QR code generation, TOTP validation, and backup code management automatically.

Implementation Patterns

Core Workflow

1. Login Flow:

   • Users authenticate with credentials → redirected to 2FA prompt (TOTP or backup code).
   • Package integrates seamlessly with Filament’s existing auth system (no manual session handling).

2. Profile Integration:

   • Add <livewire:filament-two-factor-form> to a custom profile page (e.g., Jetstream theme):

     <livewire:filament-two-factor-form />
     

   • Supports:
     • Enabling/disabling 2FA.
     • Generating new QR codes.
     • Managing backup codes.

3. Customization:

   • Views: Publish and override default views (e.g., resources/views/vendor/filament-2fa/).
   • Config: Publish config/filament-2fa.php to adjust:
     • TOTP issuer name.
     • Backup code count.
     • Recovery flow behavior.

4. Middleware:

   • Use \Webbingbrasil\FilamentTwoFactor\Http\Middleware\EnsureTwoFactorEnabled to restrict routes:

     Route::middleware([EnsureTwoFactorEnabled::class])->group(...);
     

Gotchas and Tips

Pitfalls

1. Migration Conflicts:

   • If users table already has two_factor_secret or two_factor_recovery_codes, manually merge migrations or drop columns first.
   • Run php artisan vendor:publish --tag="filament-2fa-migrations" before migrate.

2. Trait Collisions:

   • Avoid mixing with other 2FA packages (e.g., laravel-2fa). Remove conflicting traits/secrets.

3. Backup Codes:

   • Backup codes are one-time-use by default. Regenerate them via the profile form if lost.

4. Caching Issues:

   • Clear Filament cache (php artisan filament:cache:clear) after config changes or trait additions.

Debugging

• QR Code Errors:

  • Ensure google/authenticator is installed (composer require google/authenticator).
  • Check storage/logs/laravel.log for QR generation failures.

• Login Redirect Loops:

  • Verify FILAMENT_AUTH_GUARD in .env matches the guard used in config/filament.php.

Extension Points

1. Custom Recovery Flow: Override the recovery logic in app/Providers/FilamentServiceProvider.php:

   FilamentTwoFactor::recovery(function ($user, $code) {
       // Custom validation logic
   });
   

2. Event Listeners: Listen for 2FA events (e.g., TwoFactorEnabled, TwoFactorDisabled) in EventServiceProvider:

   protected $listen = [
       \Webbingbrasil\FilamentTwoFactor\Events\TwoFactorEnabled::class => [
           \App\Listeners\LogTwoFactorEnable::class,
       ],
   ];
   

3. Testing: Use the TwoFactorAuthenticatable trait’s helper methods in tests:

   $user->enableTwoFactorAuth(); // Manually enable 2FA
   $user->disableTwoFactorAuth();