> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Indagine iniziale su laravel/passkeys-server (PHP) e @laravel/passkeys (npm). Riassume installazione, integrazione con il modello User, rotte, configurazione, eventi, API frontend, errori tipizzati e supporto SSR.

<Info>
  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).
</Info>

## 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`](https://github.com/laravel/passkeys-server)
* Lato client (JavaScript): [`@laravel/passkeys`](https://github.com/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

<Steps>
  <Step title="Aggiungi il pacchetto PHP">
    ```bash theme={null}
    composer require laravel/passkeys
    ```
  </Step>

  <Step title="Pubblica ed esegui le migration">
    ```bash theme={null}
    php artisan vendor:publish --tag=passkeys-migrations
    php artisan migrate
    ```
  </Step>

  <Step title="Aggiungi trait e contract al modello User">
    ```php theme={null}
    use Laravel\Passkeys\Contracts\PasskeyUser;
    use Laravel\Passkeys\PasskeyAuthenticatable;

    class User extends Authenticatable implements PasskeyUser
    {
        use PasskeyAuthenticatable;
    }
    ```
  </Step>
</Steps>

Se necessario puoi pubblicare anche il file di configurazione.

```bash theme={null}
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

<AccordionGroup>
  <Accordion title="LoginAuthorizationCallback (autorizzazione al login)">
    Con `Passkeys::authorizeLoginUsing()` puoi controllare l'autorizzazione al login dopo il successo della verifica. Per interrompere, restituisci `false` o lancia una `ValidationException`.
  </Accordion>

  <Accordion title="CustomActions (sostituzione delle operazioni WebAuthn)">
    Puoi sostituire il comportamento estendendo `GenerateRegistrationOptions` / `GenerateVerificationOptions` / `StorePasskey` / `VerifyPasskey` / `DeletePasskey` e registrandoli nel service container.
  </Accordion>

  <Accordion title="CustomResponses (sostituzione delle risposte)">
    Implementando i contract come `PasskeyLoginResponse` puoi cambiare la risposta di successo (JSON, redirect, ecc.) secondo le esigenze dell'app.
  </Accordion>
</AccordionGroup>

## Lato client: `@laravel/passkeys`

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

### Installazione

```bash theme={null}
npm install @laravel/passkeys
```

### API di base

```js theme={null}
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.

<Info>
  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](/it/advanced/fortify).
</Info>

<Card title="laravel/passkeys-server" icon="github" href="https://github.com/laravel/passkeys-server">
  Consulta il README aggiornato e l'implementazione del pacchetto lato server.
</Card>

<Card title="@laravel/passkeys" icon="github" href="https://github.com/laravel/passkeys">
  Consulta il README aggiornato e le API del pacchetto lato client.
</Card>

<Card title="Laravel Fortify e starter kit" icon="shield-check" href="/it/advanced/fortify">
  Spiega come abilitare le passkey tramite Fortify e la relazione con gli starter kit.
</Card>


## Related topics

- [Laravel Fortify e gli starter kit](/it/advanced/fortify.md)
- [Aggiornamenti Laravel di aprile 2026](/it/blog/changelog/202604.md)
- [Laravel LSP — estensione delle funzionalità IDE tramite Language Server Protocol](/it/blog/laravel-lsp-introduction.md)
- [Guida alla migrazione da laravel/ui a Fortify](/it/blog/ui-to-fortify.md)
- [Laravel Chisel — libreria di script post-installazione per starter kit](/it/blog/chisel-introduction.md)