Filament Passkeys Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require marcelweidum/filament-passkeys
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="MarcelWeidum\FilamentPasskeys\FilamentPasskeysServiceProvider" --tag="filament-passkeys-config"
   

2. Configure Authentication: Ensure your Filament user model (App\Models\User) uses the HasPasskeys trait from the spatie/laravel-passkeys package:

   use MarcelWeidum\FilamentPasskeys\Traits\HasPasskeys;
   
   class User extends Authenticatable
   {
       use HasPasskeys;
   }
   

3. First Use Case: Replace the default Filament login form with the passkey-enabled one by registering the PasskeysLoginForm in your Filament panel provider:

   use MarcelWeidum\FilamentPasskeys\Widgets\PasskeysLoginForm;
   
   public function panel(Panel $panel): Panel
   {
       return $panel
           ->login()
           ->form(PasskeysLoginForm::class);
   }
   

Implementation Patterns

Workflow Integration

1. Seamless Migration:

   • Gradually replace traditional password-based auth with passkeys by:
     • First enabling passkey registration alongside existing password login.
     • Later, deprecating password fields in favor of passkey-only flows.
   • Use the PasskeysLoginForm widget to handle both passkey and fallback login methods.

2. Customization:

   • Override the default passkey UI by extending the PasskeysLoginForm class:

     use MarcelWeidum\FilamentPasskeys\Widgets\PasskeysLoginForm;
     
     class CustomPasskeysLoginForm extends PasskeysLoginForm
     {
         protected static ?string $passkeyRegistrationTitle = 'Register Your Biometric Key';
         protected static ?string $passkeyLoginTitle = 'Sign in with Your Device';
     }
     

3. Multi-Factor Authentication (MFA):

   • Combine with Filament’s built-in MFA or other packages by:
     • Triggering passkey verification after traditional auth (e.g., email + password).
     • Using the Passkey::verify() method in custom auth logic.

4. Registration Flow:

   • Integrate passkey registration into user onboarding:

     use MarcelWeidum\FilamentPasskeys\Facades\Passkey;
     
     public function register(Request $request)
     {
         $user = User::create($request->validated());
         Passkey::createForUser($user); // Auto-enroll in passkey flow
     }
     

5. API Integration:

   • Use the underlying spatie/laravel-passkeys API for custom endpoints:

     use MarcelWeidum\FilamentPasskeys\Facades\Passkey;
     
     Route::post('/api/passkey/register', function (Request $request) {
         return Passkey::create($request->user(), $request->input('publicKeyCredential'));
     });
     

Gotchas and Tips

Common Pitfalls

1. Browser Compatibility:

   • Passkeys require modern browsers (Chrome 115+, Edge 115+, Safari 16.4+). Test thoroughly on target devices.
   • Fallback to password login for unsupported browsers by checking the userAgent in PasskeysLoginForm.

2. Database Schema:

   • Ensure your users table has the passkey_public_key and passkey_credential_id columns (migrated by spatie/laravel-passkeys).
   • Run migrations if switching from 2.x to 3.x:

     php artisan migrate
     

3. Passkey Sync:

   • Passkeys are device-specific. If a user loses access to all registered devices, they’ll be locked out. Provide a recovery code or admin override in Filament:

     // In a Filament resource action
     public static function getActions(UserResource $resource): array
     {
         return [
             Actions\ForcePasskeyReset::make(),
         ];
     }
     

4. Testing:

   • Use spatie/laravel-passkeys's testing helpers or mock the Passkey facade:

     Passkey::shouldReceive('verify')->andReturn(true);
     

   • Test edge cases: expired sessions, multiple passkeys per user, and concurrent logins.

5. Performance:

   • Passkey verification is cryptographically intensive. Avoid blocking UI threads; use async tasks for long-running operations (e.g., passkey sync across devices).

Debugging Tips

1. Logs:

   • Enable debug mode in config/filament-passkeys.php:

     'debug' => env('APP_DEBUG', false),
     

   • Check storage/logs/laravel.log for passkey-related errors (e.g., WebAuthnException).

2. WebAuthn Errors:

   • Common errors:
     • NotAllowedError: User not verified (e.g., session expired).
     • NotSupportedError: Browser/OS doesn’t support WebAuthn.
   • Use the Passkey::errors() method to surface these to users.

3. Configuration Quirks:

   • Ensure APP_URL is correctly set in .env—passkeys rely on HTTPS and accurate origin verification.
   • If using a custom domain, update passkey_allowed_domains in the config:

     'passkey_allowed_domains' => [
         'app.yourdomain.com',
         'staging.yourdomain.com',
     ],
     

Extension Points

1. Custom Verification Logic:

   • Override the verifyPasskey method in a service class:

     use MarcelWeidum\FilamentPasskeys\Contracts\PasskeyVerifier;
     
     class CustomPasskeyVerifier implements PasskeyVerifier
     {
         public function verify($credentialId, $publicKey, $signature, $user)
         {
             // Add custom logic (e.g., rate limiting, IP checks)
             return Passkey::verify($credentialId, $publicKey, $signature, $user);
         }
     }
     

   • Bind it in AppServiceProvider:

     PasskeyVerifier::macro('custom', function () {
         return new CustomPasskeyVerifier();
     });
     

2. Passkey Metadata:

   • Attach custom metadata to passkeys (e.g., device info) by extending the Passkey model:

     class User extends Authenticatable
     {
         use HasPasskeys;
     
         protected $casts = [
             'passkey_metadata' => 'json',
         ];
     }
     

   • Access metadata during verification:

     $metadata = $user->passkeys->first()->metadata;
     

3. Passkey Events:

   • Listen for passkey events (e.g., registration, verification) using Laravel’s event system:

     // In EventServiceProvider
     protected $listen = [
         \MarcelWeidum\FilamentPasskeys\Events\PasskeyRegistered::class => [
             \App\Listeners\LogPasskeyRegistration::class,
         ],
     ];
     

4. Filament Policy Integration:

   • Restrict passkey actions (e.g., registration) to specific roles:

     use MarcelWeidum\FilamentPasskeys\Widgets\PasskeysLoginForm;
     
     PasskeysLoginForm::make()
         ->canRegister(function (User $user) {
             return $user->hasRole('admin');
         });