Laravel Passkeys — indagine iniziale (passkeys-server + @laravel/passkeys)

Questo articolo è un’indagine iniziale basata sui README di laravel/passkeys-server e laravel/passkeys. Entrambi i pacchetti sono ancora in fase di sviluppo senza tag (dato di aprile 2026).

Cosa sono questi pacchetti

Nei repository ufficiali di Laravel sono stati pubblicati due pacchetti per implementare l’autenticazione senza password (WebAuthn / passkey).

Lato server (PHP): laravel/passkeys-server
Lato client (JavaScript): @laravel/passkeys

Combinandoli puoi implementare in modo coerente registrazione e login con passkey in un’app Laravel.

Lato server: `laravel/passkeys-server`

Installazione e setup iniziale

Aggiungi il pacchetto PHP

composer require laravel/passkeys

Pubblica ed esegui le migration

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

Aggiungi trait e contract al modello User

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

class User extends Authenticatable implements PasskeyUser
{
    use PasskeyAuthenticatable;
}

Se necessario puoi pubblicare anche il file di configurazione.

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

Rotte registrate automaticamente

Sezione	Metodo	Rotta	Ruolo
Login (guest)	`GET`	`/passkeys/login/options`	Recupero opzioni di autenticazione
Login (guest)	`POST`	`/passkeys/login`	Verifica passkey e login
Confirm (auth)	`GET`	`/passkeys/confirm/options`	Recupero opzioni di conferma
Confirm (auth)	`POST`	`/passkeys/confirm`	Conferma della passkey
Management (auth)	`GET`	`/user/passkeys/options`	Recupero opzioni di registrazione
Management (auth)	`POST`	`/user/passkeys`	Salvataggio di una nuova passkey
Management (auth)	`DELETE`	`/user/passkeys/{passkey}`	Eliminazione di una passkey

Opzioni principali di `config/passkeys.php`

relying_party_id
allowed_origins
user_handle_secret
timeout
guard
middleware
throttle
redirect

Eventi

Il pacchetto emette i seguenti eventi.

PasskeyRegistered
PasskeyVerified
PasskeyDeleted

Punti di personalizzazione

CustomActions (sostituzione delle operazioni WebAuthn)

Puoi sostituire il comportamento estendendo GenerateRegistrationOptions / GenerateVerificationOptions / StorePasskey / VerifyPasskey / DeletePasskey e registrandoli nel service container.

CustomResponses (sostituzione delle risposte)

Implementando i contract come PasskeyLoginResponse puoi cambiare la risposta di successo (JSON, redirect, ecc.) secondo le esigenze dell’app.

Lato client: `@laravel/passkeys`

@laravel/passkeys è un client JavaScript che gestisce la cerimonia WebAuthn nel browser.

Installazione

npm install @laravel/passkeys

API di base

import { Passkeys } from "@laravel/passkeys";

await Passkeys.register({ name: "My MacBook" });
await Passkeys.verify();

Helper per framework

React: usePasskeyVerify, usePasskeyRegister da @laravel/passkeys/react
Vue: usePasskeyVerify, usePasskeyRegister da @laravel/passkeys/vue
Svelte: usePasskeyVerify, usePasskeyRegister da @laravel/passkeys/svelte

Passkey autofill

Specificando autofill: true, il picker delle passkey del browser viene mostrato per gli input che hanno autocomplete="... webauthn". In ambienti non supportati o quando l’utente annulla, si ricade sul flusso normale.

Errori tipizzati

Il README espone le seguenti classi di errore.

NotSupportedError
UserCancelledError
PasskeyExistsError
PasskeyError (classe base)

Supporto SSR

WebAuthn è un’API del browser, ma gli hook per ciascun framework sono SSR-safe. Lato server isSupported è trattato come false e, dopo il mount, viene aggiornato allo stato reale del browser.

Conclusioni

Combinando laravel/passkeys-server (PHP) e @laravel/passkeys (JS) puoi costruire uno stack di autenticazione con passkey completamente basato su Laravel.
Entrambi sono in fase di sviluppo senza tag, ma è molto probabile che diventino il metodo di autenticazione standard nell’ecosistema ufficiale di Laravel.
Se adotti in anticipo, è più sicuro progettare tenendo come base rotte, configurazione, gestione errori e punti di estensione descritti nel README.

In seguito le passkey sono state aggiunte ufficialmente come funzionalità di Laravel Fortify. Per abilitarle tramite Fortify usa Features::passkeys() invece di installare direttamente laravel/passkeys-server. Per i dettagli consulta Laravel Fortify e starter kit.

laravel/passkeys-server

Consulta il README aggiornato e l’implementazione del pacchetto lato server.