PHPackages omdasoft/laravel-webauthn - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Authentication & Authorization](/categories/authentication) 4. / 5. omdasoft/laravel-webauthn ActiveLibrary[Authentication & Authorization](/categories/authentication) omdasoft/laravel-webauthn ========================= A WebAuthn (passkeys) backend API package for Laravel — API-first, action-based, and fully customizable. v1.0.0(1mo ago)14MITPHPPHP ^8.3CI passing Since Apr 21Pushed 1mo agoCompare [ Source](https://github.com/omdasoft/laravel-webauthn)[ Packagist](https://packagist.org/packages/omdasoft/laravel-webauthn)[ Docs](https://github.com/omdasoft/laravel-webauthn)[ GitHub Sponsors](https://github.com/omdasoft)[ RSS](/packages/omdasoft-laravel-webauthn/feed)WikiDiscussions main Synced 1w ago READMEChangelog (1)Dependencies (16)Versions (2)Used By (0) Laravel WebAuthn ================ [](#laravel-webauthn) [![Latest Version on Packagist](https://camo.githubusercontent.com/1955856b8a6002b7b6be66d2c188b328d6f0cd315d85775f141a96179405a21f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6f6d6461736f66742f6c61726176656c2d776562617574686e2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/omdasoft/laravel-webauthn)[![Total Downloads](https://camo.githubusercontent.com/199b372f3c475849bb74ed98d04bba294a979b4620fda78ddc7f84418f8fbe36/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6f6d6461736f66742f6c61726176656c2d776562617574686e2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/omdasoft/laravel-webauthn)[![Tests](https://camo.githubusercontent.com/96167191b0f0dcb7a2d37078a2c123bfbf43cea33b0d445e8668e93657f23169/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6f6d6461736f66742f6c61726176656c2d776562617574686e2f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/omdasoft/laravel-webauthn/actions/workflows/run-tests.yml)[![PHPStan](https://camo.githubusercontent.com/ecb3a595f980b91ec19356420db54eaabfe2f6d15c24790991ea49883cf231eb/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6f6d6461736f66742f6c61726176656c2d776562617574686e2f7068707374616e2e796d6c3f6272616e63683d6d61696e266c6162656c3d7068707374616e267374796c653d666c61742d737175617265)](https://github.com/omdasoft/laravel-webauthn/actions/workflows/phpstan.yml)[![License](https://camo.githubusercontent.com/c6939eb4121113e723bf49c3ad6c3ae55e856bf3aff8e5de2ce8e19e03e47433/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6f6d6461736f66742f6c61726176656c2d776562617574686e2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/omdasoft/laravel-webauthn) A Laravel package that provides a **backend API implementation** for WebAuthn (passkeys) authentication, designed for **API-first applications** with separate frontends. Perfect for: - Single Page Applications (SPAs) - Mobile applications - Headless Laravel setups The package provides: - **API-only WebAuthn endpoints** - Pure JSON API suitable for SPAs and mobile apps. - **Action-based architecture** - Core logic is separated into dedicated Action classes for easy customization. - **Configurable models** - Support for custom Passkey and User models. - **Event-driven** - Dispatches `WebauthnLogin` upon successful authentication. - **InteractWithPasskeys trait** - Easy integration with your User (Authenticatable) model. - **Configurable API routes** - Customizable prefix and middleware support. Demo ---- [](#demo) [![Passkey registration and login demo](https://private-user-images.githubusercontent.com/64615102/581674901-dbb11185-31f1-48f8-a526-6d04c74dccf5.gif?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3ODA5NzUxMTgsIm5iZiI6MTc4MDk3NDgxOCwicGF0aCI6Ii82NDYxNTEwMi81ODE2NzQ5MDEtZGJiMTExODUtMzFmMS00OGY4LWE1MjYtNmQwNGM3NGRjY2Y1LmdpZj9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNjA2MDklMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjYwNjA5VDAzMTMzOFomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPTU0YWU5MzA0OGRmNzk0MjU5Njg0YmU3ODM3ZTRkZmI4ODk2YzJkN2QzYzVkMGFhNmM1ZmFmMzM0MTk5MDliMzAmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0JnJlc3BvbnNlLWNvbnRlbnQtdHlwZT1pbWFnZSUyRmdpZiJ9.YvA1S9Q7nWgmemUCbIcY5kZkiyHUEBwdfx3JpsRuR4U)](https://private-user-images.githubusercontent.com/64615102/581674901-dbb11185-31f1-48f8-a526-6d04c74dccf5.gif?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3ODA5NzUxMTgsIm5iZiI6MTc4MDk3NDgxOCwicGF0aCI6Ii82NDYxNTEwMi81ODE2NzQ5MDEtZGJiMTExODUtMzFmMS00OGY4LWE1MjYtNmQwNGM3NGRjY2Y1LmdpZj9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNjA2MDklMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjYwNjA5VDAzMTMzOFomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPTU0YWU5MzA0OGRmNzk0MjU5Njg0YmU3ODM3ZTRkZmI4ODk2YzJkN2QzYzVkMGFhNmM1ZmFmMzM0MTk5MDliMzAmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0JnJlc3BvbnNlLWNvbnRlbnQtdHlwZT1pbWFnZSUyRmdpZiJ9.YvA1S9Q7nWgmemUCbIcY5kZkiyHUEBwdfx3JpsRuR4U)Project Status -------------- [](#project-status) This package is **stable** and ready for production use. All breaking changes are documented in [CHANGELOG.md](CHANGELOG.md) and follow [Semantic Versioning](https://semver.org). Found a bug? [Open an issue](https://github.com/omdasoft/laravel-webauthn/issues). Want to contribute? Read [CONTRIBUTING.md](CONTRIBUTING.md). Requirements ------------ [](#requirements) - PHP `^8.3` - Laravel `10|11|12|13` Installation ------------ [](#installation) Install the package via Composer: ``` composer require omdasoft/laravel-webauthn ``` Publish the config, migration, and translations: ``` php artisan vendor:publish --provider="Omdasoft\LaravelWebauthn\LaravelWebauthnServiceProvider" ``` Or publish individually: ``` php artisan vendor:publish --tag="webauthn-config" php artisan vendor:publish --tag="webauthn-migrations" php artisan vendor:publish --tag="webauthn-translations" ``` Run migrations: ``` php artisan migrate ``` Configuration ------------- [](#configuration) After publishing, you can configure the package in `config/webauthn.php`. - **`relying_party.id`** - The relying party ID used for WebAuthn (usually the domain without protocol). - Set `WEBAUTHN_RELYING_PARTY_ID` in your `.env`. - Example: `example.com` - **`models.passkey`** - The model class used for storing passkeys. - Default: `Omdasoft\LaravelWebauthn\Models\Passkey` - **`models.authenticatable`** - Your application's user model class. - Default: `App\Models\User` - **`actions.handle_login`** - The class that handles user login after successful WebAuthn assertion (login). - Built-in options: - `Omdasoft\LaravelWebauthn\Actions\Login\HandleSanctumLogin` (Default) - `Omdasoft\LaravelWebauthn\Actions\Login\HandleSessionLogin` - You can also create your own by implementing `HandleLoginAction`. ``` WEBAUTHN_RELYING_PARTY_ID=example.com WEBAUTHN_RELYING_PARTY_NAME="My Awesome App" WEBAUTHN_ROUTE_PREFIX=api/webauthn WEBAUTHN_STORAGE_DRIVER=cache WEBAUTHN_CHALLENGE_TTL=3600 ``` Challenge Storage ----------------- [](#challenge-storage) WebAuthn requires a challenge to be stored on the server between the initial "options" request and the final verification request. You can choose how this is stored: - **`cache` (Default)**: Recommended for **stateless APIs** and applications using **Sanctum with Bearer tokens**. The challenge is retrieved using the `challenge_id` sent by the client. - **`session`**: Recommended for **stateful applications** (Inertia.js, Livewire, or Blade). This requires the client to support cookies to persist the session between requests. Update your `.env` to choose the driver: ``` WEBAUTHN_STORAGE_DRIVER=cache ``` Translations ------------ [](#translations) The package includes translatable error messages. You can publish them to customize the text: ``` php artisan vendor:publish --tag="webauthn-translations" ``` The translations will be available in `resources/lang/vendor/webauthn/en/errors.php`. Flexibility and Custom Auth --------------------------- [](#flexibility-and-custom-auth) This package is designed to be flexible. It works with Sanctum (default), Session, JWT, or any other authentication system. ### Customizing Middleware [](#customizing-middleware) Update your `config/webauthn.php`: ``` 'middlewares' => [ 'register' => ['auth:sanctum'], // Protect registration 'login' => [], // Usually public ], ``` ### Customizing Login Logic [](#customizing-login-logic) If you want to use standard Laravel sessions instead of Sanctum tokens, update `config/webauthn.php`: ``` 'actions' => [ 'handle_login' => \Omdasoft\LaravelWebauthn\Actions\Login\HandleSessionLogin::class, ], ``` For completely custom logic (e.g., JWT), create a class that implements `HandleLoginAction`: ``` namespace App\Actions; use Omdasoft\LaravelWebauthn\Contracts\HandleLoginAction; use Illuminate\Contracts\Auth\Authenticatable; class MyCustomLoginHandler implements HandleLoginAction { public function execute(Authenticatable $user): array { // Your custom logic here return ['status' => 'success', 'custom_field' => 'value']; } } ``` Model setup ----------- [](#model-setup) Add the `InteractWithPasskeys` trait and `HasPasskey` contract to your user model: ``` use Omdasoft\LaravelWebauthn\Contracts\HasPasskey; use Omdasoft\LaravelWebauthn\Traits\InteractWithPasskeys; use Illuminate\Foundation\Auth\User as Authenticatable; class User extends Authenticatable implements HasPasskey { use InteractWithPasskeys; } ``` ### Customizing User Identification [](#customizing-user-identification) If you want to change how the user's name or display name is sent to the authenticator (e.g., for the passkey creation prompt), you can override these methods in your `User` model: ``` public function getPasskeyIdentifier(): string // Default: $this->id { return (string) $this->uuid; } public function getPasskeyName(): string // Default: $this->email { return $this->username; } public function getPasskeyDisplayName(): string // Default: $this->name { return $this->full_name; } ``` API Routes and Endpoints ------------------------ [](#api-routes-and-endpoints) The package registers the following routes under your configured prefix (default: `webauthn`): ### Registration (Attestation) [](#registration-attestation) - `POST /register/options` - Get creation options. - `POST /register` - Submit attestation response. Accepts an optional `name` field to label the passkey. ### Login (Assertion) [](#login-assertion) - `POST /login/options` - Get assertion options. - `POST /login` - Submit assertion response. Error Handling -------------- [](#error-handling) The package throws specific exceptions when something goes wrong. These exceptions return translatable messages: - `ChallengeMissingException`: The challenge ID was not provided. - `ChallengeNotFoundException`: The challenge has expired or does not exist. - `UserUnauthenticatedException`: Registration attempted without being logged in. - `PasskeyNotFoundException`: The passkey requested for login was not found. - `UserNotFoundException`: The user associated with the passkey was not found. Events ------ [](#events) The package dispatches: - `Omdasoft\LaravelWebauthn\Events\WebauthnLogin`: Dispatched after a successful login. ``` public function handle(WebauthnLogin $event) { // $event->user is the logged-in user } ``` Frontend Implementation ----------------------- [](#frontend-implementation) Since this is an API-first package, you need a frontend library to interact with the browser's WebAuthn API. We recommend using [@simplewebauthn/browser](https://simplewebauthn.io/docs/packages/browser). ### 1. Registering a Passkey [](#1-registering-a-passkey) ``` import { startRegistration } from '@simplewebauthn/browser'; const registerPasskey = async () => { // 1. Get registration options from your Laravel API const resp = await axios.post('/webauthn/register/options'); const { challenge_id, passkey: options } = resp.data; // 2. Start the browser registration process const attestationResponse = await startRegistration(options); // 3. Send the response back to your API to complete registration await axios.post('/webauthn/register', { challenge_id, passkey: attestationResponse, name: 'My MacBook Pro' // Optional name for the passkey }); }; ``` ### 2. Logging in with a Passkey [](#2-logging-in-with-a-passkey) ``` import { startAuthentication } from '@simplewebauthn/browser'; const loginWithPasskey = async () => { try { // 1. Get authentication options const resp = await axios.post('/webauthn/login/options'); const { challenge_id, passkey: options } = resp.data; // 2. Pass options to the browser API const assertionResponse = await startAuthentication(options); // 3. Complete authentication const loginResp = await axios.post('/webauthn/login', { challenge_id, passkey: assertionResponse }); // 4. Handle success (e.g., redirect or update state) window.location.href = '/dashboard'; } catch (error) { console.error('Passkey authentication failed', error); } }; ``` Testing and quality ------------------- [](#testing-and-quality) ``` composer ci ``` License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 40 — FairBetter than 86% of packages Maintenance90 Actively maintained with recent releases Popularity6 Limited adoption so far Community9 Small or concentrated contributor base Maturity48 Maturing project, gaining track record Bus Factor1 Top contributor holds 85.1% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 49d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/8497aaa98f491ac955c1b8fa8c87ca6a715b26ad7571b856385ee0ff8bd8b8e1?d=identicon)[omda](/maintainers/omda) --- Top Contributors [![omdasoft](https://avatars.githubusercontent.com/u/64615102?v=4)](https://github.com/omdasoft "omdasoft (57 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (7 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (3 commits)") --- Tags laravelAuthenticationFIDO2webauthnPasswordlesspasskeypasskeysomdasoftlaravel-webauthn ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/omdasoft-laravel-webauthn/health.svg) ``` [![Health](https://phpackages.com/badges/omdasoft-laravel-webauthn/health.svg)](https://phpackages.com/packages/omdasoft-laravel-webauthn) ``` ### Alternatives [craftcms/cms Craft CMS 3.6k3.6M2.9k](/packages/craftcms-cms)[web-auth/webauthn-lib FIDO2/Webauthn Support For PHP 1237.8M117](/packages/web-auth-webauthn-lib)[web-auth/webauthn-framework FIDO2/Webauthn library for PHP and Symfony Bundle. 51090.8k2](/packages/web-auth-webauthn-framework)[rawilk/profile-filament-plugin Profile & MFA starter kit for filament. 3913.7k](/packages/rawilk-profile-filament-plugin)[spatie/laravel-permission Permission handling for Laravel 12 and up 12.9k98.0M1.3k](/packages/spatie-laravel-permission)[spatie/laravel-passkeys Use passkeys in your Laravel app 463755.5k32](/packages/spatie-laravel-passkeys) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)