Loheide-eu-mitarbeiterplatt.../vendor/laravel/passkeys
Friederich Loheide 9c0f8de791
Some checks failed
CI / PHP 8.3 / mariadb:10.6 (pull_request) Successful in 1m14s
CI / PHP 8.4 / mariadb:10.6 (pull_request) Successful in 1m12s
CI / PHP 8.4 / mariadb:11.4 (pull_request) Successful in 1m7s
CI / PHP 8.3 / mariadb:11.4 (pull_request) Successful in 1m19s
CI / PHP 8.3 / mysql:8.0 (pull_request) Successful in 1m32s
CI / PHP 8.4 / mysql:8.0 (pull_request) Successful in 1m22s
CI / PHP 8.4 / mysql:8.4 (pull_request) Successful in 1m32s
CI / PHP 8.3 / mysql:8.4 (pull_request) Successful in 1m35s
CI / Build-Artefakte aktuell (pull_request) Failing after 1m7s
Phase 0: Fundament für Inhaus
- Laravel 13 mit Filament 5 (Admin), Inertia 3 + Vue 3 + Vuetify 4 (Material 3)
- Anmeldung über Fortify (Login, Passwort vergessen/ändern), keine Selbstregistrierung
- Profil mit Profilbild (WebP in festen Größen), Personenseiten, Header mit Avatar-Menü
- Material-3-Farbschema aus der Primärfarbe, hell/dunkel/System pro Person
- Basis-Branding (Portalname, Logo, Primärfarbe) im Admin unter „Erscheinungsbild“
- Benutzerverwaltung im Admin, Zugang vorläufig über is_admin
- vendor/ (ohne Dev-Pakete) und Frontend-Build mitversioniert, Dev-Pakete in vendor-dev/
- PHPUnit-Tests gegen MySQL/MariaDB, Forgejo-CI-Matrix, Docker-Entwicklungsumgebung
- VERSION, CHANGELOG.md und CONTRIBUTING.md mit Release-Ablauf

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-25 20:35:30 +00:00
..
config Phase 0: Fundament für Inhaus 2026-09-25 20:35:30 +00:00
database/migrations Phase 0: Fundament für Inhaus 2026-09-25 20:35:30 +00:00
resources Phase 0: Fundament für Inhaus 2026-09-25 20:35:30 +00:00
routes Phase 0: Fundament für Inhaus 2026-09-25 20:35:30 +00:00
scripts Phase 0: Fundament für Inhaus 2026-09-25 20:35:30 +00:00
src Phase 0: Fundament für Inhaus 2026-09-25 20:35:30 +00:00
composer.json Phase 0: Fundament für Inhaus 2026-09-25 20:35:30 +00:00
LICENSE.md Phase 0: Fundament für Inhaus 2026-09-25 20:35:30 +00:00
phpstan-baseline.neon Phase 0: Fundament für Inhaus 2026-09-25 20:35:30 +00:00
pint.json Phase 0: Fundament für Inhaus 2026-09-25 20:35:30 +00:00
README.md Phase 0: Fundament für Inhaus 2026-09-25 20:35:30 +00:00
rector.php Phase 0: Fundament für Inhaus 2026-09-25 20:35:30 +00:00

Laravel Passkeys

Passwordless authentication using WebAuthn/passkeys for Laravel.

Installation

composer require laravel/passkeys

Publish and run the migrations:

php artisan vendor:publish --tag=passkeys-migrations
php artisan migrate

Optionally publish the config file:

php artisan vendor:publish --tag=passkeys-config

Add the PasskeyAuthenticatable trait to your User model and implement the PasskeyUser contract:

use Laravel\Passkeys\Contracts\PasskeyUser;
use Laravel\Passkeys\PasskeyAuthenticatable;

class User extends Authenticatable implements PasskeyUser
{
    use PasskeyAuthenticatable;
}

The trait assumes a standard users schema with name and email columns, which authenticators show in their UI during registration and account selection. displayName falls back from name to email to the auth identifier, and username falls back from email to the auth identifier — override getPasskeyDisplayName() and getPasskeyUsername() if you want different values.

If you want to use custom models, override them in a service provider:

use App\Models\User;
use App\Models\Passkey;
use Laravel\Passkeys\Passkeys;

public function boot(): void
{
    Passkeys::useUserModel(User::class);
    Passkeys::usePasskeyModel(Passkey::class);
}

JavaScript Client

This package is designed to work with the @laravel/passkeys npm package:

npm install @laravel/passkeys
import { Passkeys } from '@laravel/passkeys'

// Registration (authenticated user)
await Passkeys.register({ name: 'My MacBook' })

// Verification (login)
await Passkeys.verify()

Routes

The package automatically registers the following routes:

Guest Routes (Login)

  • GET /passkeys/login/options - Get login options
  • POST /passkeys/login - Verify passkey and authenticate

Authenticated Routes (Confirmation)

  • GET /passkeys/confirm/options - Get confirmation options
  • POST /passkeys/confirm - Confirm password via passkey

Authenticated Routes (Management)

  • GET /user/passkeys/options - Get registration options
  • POST /user/passkeys - Store new passkey
  • DELETE /user/passkeys/{passkey} - Delete passkey

Configuration

// config/passkeys.php

return [
    // Relying Party ID (defaults to APP_URL host)
    'relying_party_id' => parse_url(config('app.url'), PHP_URL_HOST),

    // Origins allowed to complete WebAuthn ceremonies
    'allowed_origins' => [config('app.url')],

    // Secret for deriving stable opaque user handles
    'user_handle_secret' => env('PASSKEYS_USER_HANDLE_SECRET', config('app.key')),

    // WebAuthn timeout in milliseconds
    'timeout' => 60000,

    // Authentication guard
    'guard' => 'web',

    // Routes middleware
    'middleware' => ['web'],

    // Middleware applied to passkey management routes (set to [] to disable)
    'management_middleware' => ['password.confirm'],

    // Throttle middleware (null to disable)
    'throttle' => 'throttle:6,1',

    // Redirect after login
    'redirect' => '/',
];

Events

The package fires the following events:

  • PasskeyRegistered - When a new passkey is registered
  • PasskeyVerified - When a user verifies with a passkey
  • PasskeyDeleted - When a passkey is deleted

Customization

Login Authorization Callback

You may block login after a valid passkey assertion (for example, suspended/banned accounts):

use Illuminate\Http\Request;
use Illuminate\Validation\ValidationException;
use Laravel\Passkeys\Contracts\PasskeyUser;
use Laravel\Passkeys\Passkey;
use Laravel\Passkeys\Passkeys;

Passkeys::authorizeLoginUsing(function (Request $request, PasskeyUser $user, Passkey $passkey): bool {
    if ($user->is_banned) {
        throw ValidationException::withMessages([
            'credential' => ['This account has been banned.'],
        ]);
    }

    return true;
});

Return false to stop authentication, or throw your own ValidationException for a custom error message.

User-Bound Verification (Reauth / 2FA Step)

Use GenerateVerificationOptions with an authenticated user to scope allowed credentials to that user, then pass the same user into VerifyPasskey to enforce ownership:

use Laravel\Passkeys\Actions\GenerateVerificationOptions;
use Laravel\Passkeys\Actions\VerifyPasskey;

$options = app(GenerateVerificationOptions::class)($request->user());

$passkey = app(VerifyPasskey::class)(
    $request->credential(),
    $options,
    $request->user(),
);

This verifies the passkey without logging the user in again, which is useful for sensitive-action confirmation flows.

Custom Actions

Actions handle the core WebAuthn logic. Extend an action and bind it in your service provider:

use Laravel\Passkeys\Actions\GenerateRegistrationOptions;
use Webauthn\AuthenticatorSelectionCriteria;

class CustomRegistrationOptions extends GenerateRegistrationOptions
{
    public function authenticatorSelection(): AuthenticatorSelectionCriteria
    {
        // Only allow platform authenticators (Touch ID, Face ID, Windows Hello)
        return AuthenticatorSelectionCriteria::create(
            authenticatorAttachment: AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_PLATFORM,
            userVerification: AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_REQUIRED,
            residentKey: AuthenticatorSelectionCriteria::RESIDENT_KEY_REQUIREMENT_REQUIRED,
        );
    }
}

// In your service provider
$this->app->bind(GenerateRegistrationOptions::class, CustomRegistrationOptions::class);

Available actions:

  • GenerateRegistrationOptions
  • GenerateVerificationOptions
  • StorePasskey
  • VerifyPasskey
  • DeletePasskey

Custom Responses

Bind your own response classes to customize what happens after passkey operations:

use Laravel\Passkeys\Contracts\PasskeyLoginResponse;

class MyLoginResponse implements PasskeyLoginResponse
{
    public function toResponse($request)
    {
        return response()->json(['redirect' => '/dashboard']);
    }
}

// In your service provider
$this->app->singleton(PasskeyLoginResponse::class, MyLoginResponse::class);

Available response contracts:

  • PasskeyLoginResponse - After successful login
  • PasskeyConfirmationResponse - After successful confirmation
  • PasskeyRegistrationResponse - After successful registration
  • PasskeyDeletedResponse - After passkey deletion

Custom Passkey Model

Extend the base model:

use Laravel\Passkeys\Passkey as BasePasskey;

class Passkey extends BasePasskey
{
    protected static function booted(): void
    {
        static::created(function ($passkey) {
            // Custom logic when passkey is created
        });
    }
}

Disable Routes

To register your own routes:

use Laravel\Passkeys\Passkeys;

Passkeys::ignoreRoutes();

Testing

composer test

License

The MIT License (MIT). Please see License File for more information.