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

# Première analyse de Laravel Passkeys (passkeys-server + @laravel/passkeys)

> Première analyse de laravel/passkeys-server (PHP) et @laravel/passkeys (npm). De l'installation à l'intégration au modèle User, les routes, la configuration, les événements, l'API frontend, les erreurs typées et le support SSR.

<Info>
  Cet article est une analyse initiale basée sur les README de `laravel/passkeys-server` et `laravel/passkeys`. Les deux packages sont en phase de développement, sans tag (à la date d'avril 2026).
</Info>

## De quoi s'agit-il ?

Le dépôt officiel Laravel publie deux packages pour implémenter une authentification sans mot de passe (WebAuthn / passkeys).

* Côté serveur (PHP) : [`laravel/passkeys-server`](https://github.com/laravel/passkeys-server)
* Côté client (JavaScript) : [`@laravel/passkeys`](https://github.com/laravel/passkeys)

Combinés, ils permettent d'implémenter de bout en bout l'enregistrement et la connexion par passkey dans une application Laravel.

## Côté serveur : `laravel/passkeys-server`

### Installation et configuration initiale

<Steps>
  <Step title="Ajouter le package PHP">
    ```bash theme={null}
    composer require laravel/passkeys
    ```
  </Step>

  <Step title="Publier et exécuter les migrations">
    ```bash theme={null}
    php artisan vendor:publish --tag=passkeys-migrations
    php artisan migrate
    ```
  </Step>

  <Step title="Ajouter le trait et le contract au modèle User">
    ```php theme={null}
    use Laravel\Passkeys\Contracts\PasskeyUser;
    use Laravel\Passkeys\PasskeyAuthenticatable;

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

Le fichier de configuration peut être publié si besoin.

```bash theme={null}
php artisan vendor:publish --tag=passkeys-config
```

### Routes enregistrées automatiquement

| Catégorie         | Méthode  | Route                       | Rôle                                        |
| ----------------- | -------- | --------------------------- | ------------------------------------------- |
| Login (invité)    | `GET`    | `/passkeys/login/options`   | Récupération des options d'authentification |
| Login (invité)    | `POST`   | `/passkeys/login`           | Vérification de la passkey et connexion     |
| Confirm (auth)    | `GET`    | `/passkeys/confirm/options` | Récupération des options de confirmation    |
| Confirm (auth)    | `POST`   | `/passkeys/confirm`         | Confirmation de la passkey                  |
| Management (auth) | `GET`    | `/user/passkeys/options`    | Récupération des options d'enregistrement   |
| Management (auth) | `POST`   | `/user/passkeys`            | Enregistrement d'une nouvelle passkey       |
| Management (auth) | `DELETE` | `/user/passkeys/{passkey}`  | Suppression d'une passkey                   |

### Options principales de `config/passkeys.php`

* `relying_party_id`
* `allowed_origins`
* `user_handle_secret`
* `timeout`
* `guard`
* `middleware`
* `throttle`
* `redirect`

### Événements

Le package déclenche les événements suivants.

* `PasskeyRegistered`
* `PasskeyVerified`
* `PasskeyDeleted`

### Points de personnalisation

<AccordionGroup>
  <Accordion title="LoginAuthorizationCallback (autorisation de connexion)">
    `Passkeys::authorizeLoginUsing()` permet de contrôler l'autorisation de connexion après une vérification réussie. Pour l'interrompre, retournez `false` ou levez une `ValidationException`.
  </Accordion>

  <Accordion title="CustomActions (remplacement du traitement WebAuthn)">
    En héritant de `GenerateRegistrationOptions`, `GenerateVerificationOptions`, `StorePasskey`, `VerifyPasskey` ou `DeletePasskey` et en les liant au conteneur, vous pouvez modifier leur comportement.
  </Accordion>

  <Accordion title="CustomResponses (remplacement des réponses)">
    En implémentant vos propres contracts comme `PasskeyLoginResponse`, vous adaptez les réponses de succès (JSON, redirections, etc.) aux besoins de votre application.
  </Accordion>
</AccordionGroup>

## Côté client : `@laravel/passkeys`

`@laravel/passkeys` est un client JavaScript qui prend en charge la cérémonie WebAuthn côté navigateur.

### Installation

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

### API de base

```js theme={null}
import { Passkeys } from "@laravel/passkeys";

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

### Helpers par framework

* React : `usePasskeyVerify`, `usePasskeyRegister` dans `@laravel/passkeys/react`
* Vue : `usePasskeyVerify`, `usePasskeyRegister` dans `@laravel/passkeys/vue`
* Svelte : `usePasskeyVerify`, `usePasskeyRegister` dans `@laravel/passkeys/svelte`

### Autofill de passkey

En spécifiant `autofill: true`, le sélecteur de passkeys du navigateur s'affiche pour les `input` ayant `autocomplete="... webauthn"`. En cas d'environnement non supporté ou d'annulation utilisateur, le flux retombe sur le parcours classique.

### Erreurs typées

Le README expose les classes d'erreur suivantes.

* `NotSupportedError`
* `UserCancelledError`
* `PasskeyExistsError`
* `PasskeyError` (classe de base)

### Support SSR

WebAuthn est une API navigateur, mais les hooks de chaque framework sont sûrs pour le SSR. Côté serveur, `isSupported` est traité comme `false` et est mis à jour côté navigateur après le montage.

## Conclusion

* La combinaison `laravel/passkeys-server` (PHP) et `@laravel/passkeys` (JS) permet de construire une pile d'authentification par passkey complète et cohérente dans Laravel.
* Les deux packages sont en phase de développement sans tag, mais il est très probable qu'ils deviennent la méthode d'authentification standard de l'écosystème officiel Laravel.
* Pour une adoption précoce, basez votre conception sur les routes, la configuration, la gestion d'erreurs et les points de personnalisation décrits dans le README.

<Info>
  Par la suite, les passkeys ont été **officiellement ajoutées comme fonctionnalité de Laravel Fortify**. Pour activer les passkeys via Fortify, utilisez `Features::passkeys()` au lieu d'installer directement `laravel/passkeys-server`. Voir [Laravel Fortify et starter kits](/fr/advanced/fortify) pour les détails.
</Info>

<Card title="laravel/passkeys-server" icon="github" href="https://github.com/laravel/passkeys-server">
  Consultez le README et l'implémentation du package côté serveur.
</Card>

<Card title="@laravel/passkeys" icon="github" href="https://github.com/laravel/passkeys">
  Consultez le README et l'API du package côté client.
</Card>

<Card title="Laravel Fortify et starter kits" icon="shield-check" href="/fr/advanced/fortify">
  Procédure d'activation des passkeys via Fortify et relation avec les starter kits.
</Card>


## Related topics

- [Mises à jour Laravel — avril 2026](/fr/blog/changelog/202604.md)
- [Laravel Fortify et les starter kits](/fr/advanced/fortify.md)
- [Guide de migration de laravel/ui vers Fortify](/fr/blog/ui-to-fortify.md)
- [Laravel Chisel — la bibliothèque de scripts post-installation des starter kits](/fr/blog/chisel-introduction.md)
- [Kits de démarrage](/fr/starter-kits.md)