Laravel Passkeys Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Native Laravel Integration: Built for Laravel, leveraging its ecosystem (Livewire, Blade, Events) with minimal friction.
  • WebAuthn Compliance: Uses webauthn-lib (v5.3+), adhering to FIDO2/CTAP2 standards for passkey authentication.
  • Modular Design: Decouples passkey logic (registration/authentication) from business logic, enabling reuse across features (e.g., admin panels, user dashboards).
  • Event-Driven: Supports PasskeyRegisteredEvent, allowing integration with analytics, notifications, or audit logs.
  • Multi-Factor Ready: Can coexist with Laravel’s existing auth (e.g., remember_me, session management).

• Cons:

  • Tight Coupling to Livewire: Requires Livewire for passkey generation (Blade component for auth). Teams using Inertia.js or alternative frontends may need wrappers.
  • Limited Customization: Predefined UI flows (e.g., passkey registration steps) may conflict with custom auth pipelines.
  • No Built-in Rate Limiting: Relies on Laravel’s middleware for security (e.g., throttling passkey attempts).

Integration Feasibility

• Laravel Version Support: Officially supports Laravel 10–13 (as of v1.6.3). Backward compatibility with older versions may require adjustments.
• Database Schema: Requires a passkeys table (migration provided). Assumes a users table with id and email fields.
• Dependencies:
  • Critical: Livewire (for registration), webauthn-lib (v5.3+), PHP 8.1+.
  • Optional: Inertia.js (documented but not enforced).
• Authentication Backend: Works with Laravel’s default Authenticatable or custom guards (e.g., Sanctum, Passport).

Technical Risk

• High:
  • WebAuthn Complexity: Misconfigurations (e.g., relyingParty name, allowedOrigins) can break passkey enrollment/auth. Requires testing with real devices (e.g., iOS/Android).
  • Livewire Dependency: Teams not using Livewire must implement a custom frontend solution (e.g., Alpine.js + AJAX).
  • Browser Support: Passkeys rely on modern browsers (Chrome 89+, Safari 15.4+). Legacy support requires fallback flows.
• Medium:
  • Event System: Custom events (e.g., PasskeyRegisteredEvent) may need adaptation for existing event handlers.
  • Session Management: "Remember me" functionality requires coordination with Laravel’s session driver.
• Low:
  • Migration Path: Clear documentation and migrations reduce schema risks.
  • Testing: Comprehensive test suite (PHPUnit) covers core functionality.

Key Questions

1. Frontend Strategy:
   • Is Livewire already in use? If not, what’s the plan for passkey registration UX (e.g., custom component, Inertia.js)?
2. Fallback Mechanisms:
   • How will legacy users (without passkey support) authenticate? (e.g., SMS OTP, email magic links).
3. Security Review:
   • Are allowedOrigins and relyingParty names aligned with your domain/subdomains?
   • Is rate limiting applied to passkey endpoints (e.g., /passkey/authenticate)?
4. Multi-Region Deployment:
   • How will passkey data be stored/replicated across regions (e.g., database sharding)?
5. Compliance:
   • Does your organization require audit logs for passkey events? If so, how will PasskeyRegisteredEvent be extended?
6. Performance:
   • Will passkey authentication introduce latency? (WebAuthn challenges are CPU-intensive.)
7. User Education:
   • How will users be guided through passkey setup (e.g., tooltips, help center)?

Integration Approach

Stack Fit

• Best For:
  • Laravel applications targeting passwordless authentication with modern browsers.
  • Projects already using Livewire or willing to adopt it for passkey registration.
  • Teams prioritizing FIDO2 compliance and phishing-resistant authentication.
• Less Ideal For:
  • Legacy systems without Livewire or PHP 8.1+.
  • Applications requiring highly customized auth flows (e.g., biometric-only passkeys).
  • Non-web platforms (e.g., mobile apps would need a custom backend wrapper).

Migration Path

1. Preparation:

   • Audit Laravel version (target 10+ for full support).
   • Verify Livewire compatibility (v3 or v4).
   • Backup existing auth logic (e.g., LoginController, RegisterController).

2. Installation:

   composer require spatie/laravel-passkeys
   php artisan vendor:publish --provider="Spatie\Passkeys\PasskeysServiceProvider"
   php artisan migrate
   

   • Publish config (config/passkeys.php) to customize:
     • relying_party.name (e.g., "Acme Corp").
     • allowed_origins (e.g., ["https://app.acme.com", "https://*.acme.com"]).
     • authentication_options (e.g., remember_me: true).

3. Frontend Integration:

   • Livewire Route: Add to routes/web.php:

     Route::get('/passkey/register', PasskeyRegister::class)->name('passkey.register');
     

   • Blade Auth: Use @passkeyAuth in login forms:

     @passkeyAuth
     

   • Inertia.js: Follow documented steps to pass WebAuthn responses.

4. Backend Logic:

   • Extend AuthenticatesUsers or MustVerifyEmail to handle passkey auth:

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

   • Listen to events (e.g., PasskeyRegisteredEvent) for analytics:

     PasskeyRegistered::listen(function ($user, $passkey) {
         event(new UserPasskeyAdded($user, $passkey));
     });
     

5. Testing:

   • Test with real devices (passkeys don’t work in incognito/private modes).
   • Validate edge cases:
     • Multiple passkeys per user.
     • Passkey deletion/recovery.
     • Concurrent sessions.

Compatibility

• Laravel Ecosystem:
  • Sanctum/Passport: Works with token-based auth (passkeys replace passwords).
  • Fortify: Can replace Fortify’s LoginController with custom logic.
  • Breeze/Jetstream: Requires manual integration (e.g., override auth scaffolding).
• Third-Party:
  • Laravel Nova: Passkeys can replace Nova’s default auth (custom panel required).
  • Cashier/Stripe: No direct impact, but passkeys simplify user onboarding.

Sequencing

1. Phase 1 (MVP):
   • Implement passkey registration/auth for new users only.
   • Use Livewire for registration, Blade for auth.
2. Phase 2 (Enhancement):
   • Add passkey support to existing users (migrate passwords to passkeys).
   • Implement fallback flows (e.g., email OTP for unsupported browsers).
3. Phase 3 (Optimization):
   • Customize UI (e.g., Inertia.js components).
   • Add analytics for passkey adoption rates.

Operational Impact

Maintenance

• Pros:
  • Minimal Boilerplate: Package handles WebAuthn challenges, credential storage, and auth logic.
  • Active Development: Regular updates (e.g., webauthn-lib compatibility fixes).
  • Community Support: MIT license, Spatie’s responsive issue tracking.
• Cons:
  • Dependency Risks:
    • webauthn-lib updates may require config tweaks (e.g., CredentialRecord changes in v5.3).
    • Livewire updates could break registration flows.
  • Debugging Complexity:
    • WebAuthn errors (e.g., NotAllowedError) are opaque without browser dev tools.
  • Schema Management:
    • Passkey data is stored in the database; backups must include the passkeys table.

Support

• User Support:
  • Pros:
    • Reduced password resets (passkeys sync with OS keychains).
    • Phishing-resistant (no password sharing).
  • Cons:
    • Users may struggle with passkey setup (e.g., "Where’s my passkey stored?").
    • No password fallback requires clear documentation.
• Developer Support:
  • Documentation: Comprehensive but assumes familiarity with Livewire/WebAuthn.
  • Troubleshooting:
    • Common issues:
      • Incorrect allowedOrigins (CORS errors).
      • Missing `