Weave Code
Passkeys Laravel Package
laravel/passkeys
Laravel Passkeys adds passwordless WebAuthn authentication to Laravel apps, with built-in routes for passkey login, confirmation, and management, configurable relying party settings, custom model support, and a matching @laravel/passkeys JavaScript client.
Laravel Passkeys adds passwordless, WebAuthn-based authentication to Laravel applications. Register and verify passkeys through a bundled JavaScript client (@laravel/passkeys), with migrations, config, and routes provided by the package.
- Drop-in trait: implement
PasskeyUserand usePasskeyAuthenticatableon your User model - Ready-made routes for login, confirmation, and passkey management
- Custom models via
Passkeys::useUserModel()andPasskeys::usePasskeyModel() - Configurable relying party ID and allowed origins
- Sensible defaults for display name and username, easily overridden
Frequently asked questions about Passkeys
- How do I add passkey authentication to an existing Laravel app?
- Install via Composer (`composer require laravel/passkeys`), publish migrations and config (`php artisan vendor:publish --tag=passkeys-migrations --tag=passkeys-config`), then add the `PasskeyAuthenticatable` trait to your User model. Run migrations and you’re ready to use the built-in routes or JS client.
- Does this package work with Laravel 9.x or only Laravel 10+?
- The package officially supports Laravel 8.83+ and 10.x. Laravel 9.x may require minor adjustments due to named argument changes in PHP 8.1, but the core functionality should work with small tweaks. Test thoroughly if using Laravel 9.
- Can I use custom models for users or passkeys instead of the defaults?
- Yes, override the default models in a service provider using `Passkeys::useUserModel()` and `Passkeys::usePasskeyModel()`. Call these methods before routes load to avoid binding issues. This is useful for multi-tenant apps or custom database schemas.
- What browsers and devices support passkeys with this package?
- The package works with modern browsers like Chrome 115+, Safari 16+, and Edge 115+. It also supports platform authenticators (e.g., Touch ID, Windows Hello) and hardware security keys. Fallback to password auth is automatic if WebAuthn isn’t supported.
- How do I customize the passkey registration or login UI?
- Override the `getPasskeyDisplayName()` and `getPasskeyUsername()` methods in your User model to control what appears in the authenticator UI. For deeper customization, extend the `@laravel/passkeys` npm client or modify the frontend flow using the provided endpoints.
- Is there a way to enforce passkey-only authentication for certain users?
- Yes, implement the `authorizeLoginUsing()` callback in your User model to block passkey logins for specific users (e.g., suspended accounts). Combine this with middleware to redirect or enforce passkey-only flows where needed.
- How does this handle high-concurrency scenarios (e.g., 10K+ users)?
- The package uses pessimistic locking in `VerifyPasskey` to prevent race conditions. Ensure your database supports transactions (e.g., MySQL InnoDB, PostgreSQL). For extreme scale, consider sharding or optimizing your database configuration.
- Can I integrate this with a headless or API-only Laravel app?
- Yes, the package includes API-friendly routes. Override the default middleware in your `PasskeysServiceProvider` to use `api` middleware instead of `web` for API-only access. The JS client can still be used in SPAs or mobile apps.
- What happens if a passkey verification fails? Can I fall back to passwords?
- Failed passkey verifications throw a `ValidationException`. Configure middleware to catch this exception and redirect to password login. The package doesn’t enforce passkey-only auth by default, so password fallback is seamless.
- Are there alternatives to this package for Laravel passkeys?
- Other options include `webauthn/webauthn-php` (low-level) or `paragonie/webauthn` (more manual setup). This package stands out for its Laravel-native integration, built-in migrations, and JS client, reducing boilerplate significantly compared to raw WebAuthn libraries.
Weaver
How can I help you explore Laravel packages today?