Laravel Passkeys Laravel Package

Technical Evaluation

Architecture Fit

• Modern Authentication Paradigm: Aligns with FIDO2/WebAuthn standards, replacing passwords with passkeys—a future-proof, phishing-resistant solution.
• Laravel-Native Integration: Leverages Laravel’s built-in features (e.g., Authenticatable, HasApiTokens) and integrates seamlessly with Livewire/Blade, reducing architectural friction.
• Event-Driven Extensibility: Supports custom events (e.g., PasskeyRegisteredEvent) for workflows like audit logging, analytics, or multi-factor enforcement.
• Modular Design: Decouples passkey logic from core auth, enabling gradual adoption (e.g., pilot for high-risk accounts first).

Integration Feasibility

• Low-Coupling: Requires only Livewire (for registration) and minimal backend changes (e.g., Passkey model, middleware). Existing auth flows (e.g., email/password) remain untouched.
• Database Schema: Adds a passkeys table with user_id, credential_id, and metadata—compatible with Laravel’s migrations and Eloquent.
• Frontend Agnostic: Works with Livewire, Blade, or Inertia (via JS SDK), allowing hybrid adoption (e.g., passkeys for web + legacy mobile apps).

Technical Risk

• WebAuthn Library Dependencies: Relies on web-auth/webauthn-lib (v5.3+), which may introduce breaking changes (e.g., CredentialRecord type shifts). Mitigate via:
  • Version Pinning: Lock to a stable minor version (e.g., ^5.3) in composer.json.
  • Testing: Validate with webauthn-lib’s test vectors.
• Browser/OS Support: Passkeys require modern browsers (Chrome 115+, Safari 16.4+) and OS-level support (e.g., macOS Ventura). Risk:
  • Fallback Mechanisms: Provide gracefully degrading UX (e.g., "Use a password instead" links).
  • Analytics: Track adoption rates by device/browser to identify gaps.
• Security Edge Cases:
  • Relying Party Identity: Misconfigured relyingParty.name or id can break authentication. Use Laravel’s config('passkeys.relying_party').
  • Credential Storage: Ensure Passkey model’s data field is encrypted if storing sensitive metadata (e.g., publicKeyCredential).

Key Questions

1. Adoption Strategy:
   • Will passkeys replace passwords entirely, or coexist as a secondary factor? (Affects UX flow design.)
   • Should high-risk actions (e.g., admin panels) enforce passkeys while allowing passwords for low-risk flows?
2. Multi-Device Sync:
   • How will passkeys sync across devices? (Requires platform-specific handling, e.g., iCloud Keychain, Google Smart Lock.)
3. Legacy Support:
   • How to handle users without passkey-compatible devices? (Fallback to SMS/email OTP or password reset.)
4. Compliance:
   • Does your region/industry (e.g., healthcare, finance) mandate specific auth standards? Passkeys may need additional attestation (e.g., attestation: "none" vs. "direct").
5. Performance:
   • Will passkey registration/auth add latency? Benchmark WebAuthn round-trips vs. traditional auth.

Integration Approach

Stack Fit

• Laravel Ecosystem: Optimized for Laravel 10/11, with support for Livewire 3/4, Inertia, and Blade. Leverages:
  • Livewire: For real-time passkey registration (e.g., GeneratePasskey component).
  • Eloquent: Passkey model handles credential storage/retrieval.
  • Middleware: Built-in EnsurePasskeyIsVerified for protected routes.
• Frontend Compatibility:
  • Web: Native browser support via navigator.credentials.create()/get().
  • Mobile: Requires platform-specific apps (e.g., iOS Keychain, Android Smart Lock).
  • Hybrid: Inertia/React/Vue can use the WebAuthn JS SDK for custom UIs.
• Database: Adds a passkeys table with user_id, credential_id (base64), and transports (e.g., ["internal", "usb"]).

Migration Path

1. Phase 1: Pilot (Low Risk)

   • Scope: Enable passkeys for non-critical user groups (e.g., beta testers).
   • Steps:
     • Install package: composer require spatie/laravel-passkeys.
     • Publish config: php artisan vendor:publish --tag="passkeys-config".
     • Add Passkey model to User model (hasMany relationship).
     • Integrate Livewire component for registration: @livewire('generate-passkey').
   • Validation: Test with 5–10 users; monitor failure rates (e.g., unsupported devices).

2. Phase 2: Core Integration

   • Scope: Roll out to all users as a primary auth method.
   • Steps:
     • Replace password fields with passkey prompts on login (@livewire('authenticate-with-passkey')).
     • Update LoginController to handle passkey auth alongside passwords:

       use Spatie\Passkeys\AuthenticatesWithPasskeys;
       class LoginController extends Controller {
           use AuthenticatesWithPasskeys;
       }
       

     • Add middleware to enforce passkeys for sensitive routes:

       Route::middleware(['auth', 'passkey.verified'])->group(function () {
           // Admin routes
       });
       

     • Configure config/passkeys.php:

       'relying_party' => [
           'name' => 'Your App Name',
           'id' => 'yourdomain.com',
       ],
       'allowed_origins' => ['https://yourdomain.com', 'https://app.yourdomain.com'],
       

3. Phase 3: Optimization

   • Scope: Enhance UX and security.
   • Steps:
     • Add "Remember this device" functionality via authenticateWithPasskey($remember = true).
     • Implement passkey deletion: user->passkeys()->delete($credentialId).
     • Extend PasskeyRegisteredEvent for custom logic (e.g., send welcome email with passkey tips).
     • Localize UI strings (e.g., passkeys::messages.authenticate).

Compatibility

• Laravel Versions: Tested on 10/11; may require adjustments for older versions (e.g., Livewire 2).
• PHP Versions: Requires PHP 8.1+ (due to webauthn-lib dependencies).
• Browser/OS: Chrome 115+, Safari 16.4+, Edge 115+, or OS-level passkey managers (e.g., Bitwarden, 1Password).
• Conflicts:
  • Other Auth Packages: Ensure no duplicate webauthn-lib installations (use composer why-not spatie/laravel-passkeys).
  • CSRF: Passkey endpoints are CSRF-exempt by default; verify this aligns with your security policies.

Sequencing

1. Prerequisites:
   • Install Livewire: composer require livewire/livewire.
   • Ensure webauthn-lib is compatible with your PHP version.
2. Order of Operations:
   • Configure config/passkeys.php before running migrations.
   • Add Passkey model to User before using auth methods.
   • Test Livewire components in isolation before integrating with auth flows.
3. Rollback Plan:
   • If passkeys fail, maintain password fallback with minimal UX disruption.
   • Use feature flags (e.g., Laravel Nova/Flags) to toggle passkey availability.

Operational Impact

Maintenance

• Dependencies:
  • Monitor webauthn-lib for breaking changes (e.g., #120).
  • Update spatie/laravel-passkeys regularly (MIT license allows forks if needed).
• Schema Changes:
  • Migrations are backward-compatible; no data loss risk.
  • Add indexes to passkeys.user_id and credential_id for performance.
• Logging:
  • Log passkey events (e.g., registration, authentication failures) for debugging:

    PasskeyRegisteredEvent::listen(function ($event) {
        Log::info('Passkey registered', ['user_id' => $event->user->id]);
    });
    

Support

• Common Issues:
  • Device Incompatibility: Provide clear error messages (e.g., "Your browser doesn’t support passkeys. Use a password instead.").
  • Lost Passkeys: Implement a recovery flow (e.g., backup codes or