Weave Code
Laravel Passkeys Laravel Package
spatie/laravel-passkeys
Add passkey (WebAuthn) login to your Laravel app. Provides a Livewire component to create and manage passkeys and a Blade component to authenticate users without passwords, using platform authenticators like iCloud Keychain or 1Password.
Use passkeys in your Laravel app
Frequently asked questions about Laravel Passkeys
- How do I integrate passkeys into an existing Laravel auth system without breaking password logins?
- The package supports hybrid authentication out of the box. Use the `PasskeyMiddleware` to protect routes while allowing password logins to coexist. You can also extend the `Authenticatable` contract to support both passkeys and passwords via custom guards or feature flags for gradual rollout.
- Does this package work with Laravel 11, and what’s the upgrade path from Laravel 10?
- Yes, `spatie/laravel-passkeys` is fully compatible with Laravel 11. The upgrade path is straightforward—update Composer dependencies, run migrations, and ensure your Livewire version is compatible (v3.x for Laravel 11). The package follows Laravel’s semantic versioning, so minor updates are backward-compatible.
- Can I use passkeys for multi-factor authentication (MFA) instead of just replacing passwords?
- Absolutely. The package’s modular design allows you to integrate passkeys as a secondary authentication factor. Use the `PasskeyRegisteredEvent` to trigger MFA workflows, and combine it with Laravel’s existing `MustVerifyEmail` or custom middleware for layered security.
- What happens if a user loses access to their passkey device (e.g., phone or laptop)?
- The package doesn’t automatically handle passkey revocation, but you can implement custom logic via the `Passkey` model or events. For example, trigger a password fallback when a passkey authentication fails, or allow admins to revoke passkeys via a `softDelete` or custom revocation table. Always provide a grace period for users to recover.
- Is there a way to test passkey authentication without real hardware (e.g., emulators or mock devices)?
- Yes, you can use tools like **WebAuthn Emulator** (e.g., `webauthn-emulator` npm package) or browser extensions like **WebAuthn Test Tool** to simulate passkey devices. The package also supports mocking the `Webauthn` facade in PHPUnit tests. Document your test setup to ensure edge cases (e.g., failed authentications) are covered.
- How do I configure allowedOrigins for passkeys if my app uses subdomains or a mobile app?
- Set the `allowed_origins` array in the `config/passkeys.php` file to include all valid domains (e.g., `['https://app.example.com', 'https://mobile.example.com']`). For dynamic subdomains, use wildcards like `['https://*.example.com']`, but test thoroughly—misconfigurations can break authentication. The package validates origins against the WebAuthn spec.
- Can I use this package with Inertia.js or a React/Vue frontend without Livewire?
- The Livewire component is required for passkey *registration*, but you can use the Blade-based `passkey-authenticate` component for authentication in SPAs. For Inertia.js, proxy the Blade component to your frontend or build a custom API endpoint using the package’s `PasskeyAuthenticator` service. Livewire is only needed for the registration UI.
- Are there performance implications for passkey authentication compared to traditional password logins?
- Passkey authentication may introduce slight latency (~100–300ms) due to WebAuthn cryptographic operations, but this is negligible for most users. The package optimizes this by offloading challenges to the client side. For high-traffic apps, consider caching passkey metadata or using queue workers for async processing of WebAuthn responses.
- How do I handle users who don’t have passkey-supporting devices (e.g., older browsers or non-smartphones)?
- Provide a fallback to password authentication by checking the `user_agent` or `navigator` capabilities in JavaScript, then redirecting to a password form. The package includes a `PasskeyUnavailableException` you can catch to trigger fallbacks. Document this in your UI/UX to set expectations (e.g., ‘Use a password if passkeys aren’t available’).
- What alternatives exist if I need more control over WebAuthn implementation or support for additional platforms?
- For deeper customization, consider using the underlying `webauthn-lib` directly or packages like `league/webauthn` (PHP port of the spec). However, these require manual handling of challenges, sessions, and database storage. For broader platform support (e.g., YubiKey, hardware tokens), `spatie/laravel-passkeys` already covers most use cases via its abstraction layer.
Weaver
How can I help you explore Laravel packages today?