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

# Erste Analyse: Laravel Passkeys (passkeys-server + @laravel/passkeys)

> Erste Analyse von laravel/passkeys-server (PHP) und @laravel/passkeys (npm). Von Installation, User-Modell-Integration, Routen, Konfiguration, Events, Frontend-API, typisierten Fehlern bis zur SSR-Unterstützung.

<Info>
  Dieser Artikel ist eine erste Analyse auf Basis der READMEs von `laravel/passkeys-server` und `laravel/passkeys`. Beide Pakete befinden sich noch in einer Entwicklungsphase ohne Tags (Stand: April 2026).
</Info>

## Was steckt hinter diesen Paketen?

In den offiziellen Laravel-Repositories werden zwei Pakete zur Umsetzung passwortloser Authentifizierung (WebAuthn / Passkeys) bereitgestellt.

* Serverseitig (PHP): [`laravel/passkeys-server`](https://github.com/laravel/passkeys-server)
* Clientseitig (JavaScript): [`@laravel/passkeys`](https://github.com/laravel/passkeys)

Die Kombination beider Pakete erlaubt in einer Laravel-Anwendung die einheitliche Umsetzung von Passkey-Registrierung und -Login.

## Serverseitig: `laravel/passkeys-server`

### Installation und Erst-Setup

<Steps>
  <Step title="PHP-Paket hinzufügen">
    ```bash theme={null}
    composer require laravel/passkeys
    ```
  </Step>

  <Step title="Migrationen veröffentlichen und ausführen">
    ```bash theme={null}
    php artisan vendor:publish --tag=passkeys-migrations
    php artisan migrate
    ```
  </Step>

  <Step title="Trait und Contract am User-Modell ergänzen">
    ```php theme={null}
    use Laravel\Passkeys\Contracts\PasskeyUser;
    use Laravel\Passkeys\PasskeyAuthenticatable;

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

Bei Bedarf lässt sich auch die Konfigurationsdatei veröffentlichen.

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

### Automatisch registrierte Routen

| Kategorie         | Methode  | Route                       | Zweck                                      |
| ----------------- | -------- | --------------------------- | ------------------------------------------ |
| Login (guest)     | `GET`    | `/passkeys/login/options`   | Optionen für die Authentifizierung abrufen |
| Login (guest)     | `POST`   | `/passkeys/login`           | Passkey verifizieren und einloggen         |
| Confirm (auth)    | `GET`    | `/passkeys/confirm/options` | Optionen für die Bestätigung abrufen       |
| Confirm (auth)    | `POST`   | `/passkeys/confirm`         | Passkey bestätigen                         |
| Management (auth) | `GET`    | `/user/passkeys/options`    | Optionen für die Registrierung abrufen     |
| Management (auth) | `POST`   | `/user/passkeys`            | Neuen Passkey speichern                    |
| Management (auth) | `DELETE` | `/user/passkeys/{passkey}`  | Passkey löschen                            |

### Wichtige Optionen in `config/passkeys.php`

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

### Events

Das Paket löst folgende Events aus.

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

### Anpassungspunkte

<AccordionGroup>
  <Accordion title="LoginAuthorizationCallback (Zulassungsprüfung beim Login)">
    Mit `Passkeys::authorizeLoginUsing()` steuern Sie, ob nach erfolgreicher Verifikation eingeloggt werden darf. Zum Abbrechen geben Sie `false` zurück oder werfen eine `ValidationException`.
  </Accordion>

  <Accordion title="CustomActions (Austausch der WebAuthn-Verarbeitung)">
    Sie können `GenerateRegistrationOptions`, `GenerateVerificationOptions`, `StorePasskey`, `VerifyPasskey` und `DeletePasskey` erweitern, im Service-Container binden und das Verhalten ersetzen.
  </Accordion>

  <Accordion title="CustomResponses (Austausch der Responses)">
    Durch eigene Implementierungen von Contracts wie `PasskeyLoginResponse` passen Sie Erfolgs-Responses (JSON, Redirects u. a.) an Ihre Anforderungen an.
  </Accordion>
</AccordionGroup>

## Clientseitig: `@laravel/passkeys`

`@laravel/passkeys` ist ein JavaScript-Client, der die WebAuthn-Zeremonien im Browser übernimmt.

### Installation

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

### Grundlegende API

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

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

### Framework-Helfer

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

### Passkey-Autofill

Mit `autofill: true` lässt sich in Inputs mit `autocomplete="... webauthn"` der Passkey-Picker des Browsers anzeigen. In nicht unterstützten Umgebungen oder bei Nutzer-Abbruch erfolgt ein Fallback auf den normalen Ablauf.

### Typisierte Fehler

Die README stellt folgende Fehlerklassen bereit.

* `NotSupportedError`
* `UserCancelledError`
* `PasskeyExistsError`
* `PasskeyError` (Basisklasse)

### SSR-Unterstützung

WebAuthn ist zwar eine Browser-API, doch die Framework-Hooks sind SSR-sicher. Auf der Serverseite wird `isSupported` als `false` behandelt und nach dem Mount auf den echten Browser-Zustand aktualisiert.

## Fazit

* Die Kombination aus `laravel/passkeys-server` (PHP) und `@laravel/passkeys` (JS) erlaubt in Laravel den Aufbau eines vollständigen Passkey-Auth-Stacks.
* Beide Pakete befinden sich in einer Entwicklungsphase ohne Tags, dürften jedoch als offizieller Bestandteil des Laravel-Ökosystems künftig ein Standard-Authentifizierungsweg werden.
* Bei einer frühen Einführung sollten Sie das Design an Routen, Konfiguration, Fehlerbehandlung und Erweiterungspunkten aus der README ausrichten.

<Info>
  Passkeys wurden anschließend **offiziell als Feature von Laravel Fortify aufgenommen**. Um Passkeys über Fortify zu aktivieren, verwenden Sie `Features::passkeys()`, statt `laravel/passkeys-server` direkt zu installieren. Details finden Sie unter [Laravel Fortify und die Starterkits](/de/advanced/fortify).
</Info>

<Card title="laravel/passkeys-server" icon="github" href="https://github.com/laravel/passkeys-server">
  Aktuelle README und Implementierung des serverseitigen Pakets.
</Card>

<Card title="@laravel/passkeys" icon="github" href="https://github.com/laravel/passkeys">
  Aktuelle README und API des clientseitigen Pakets.
</Card>

<Card title="Laravel Fortify und die Starterkits" icon="shield-check" href="/de/advanced/fortify">
  Anleitung zum Aktivieren von Passkeys über Fortify und der Zusammenhang mit den Starterkits.
</Card>


## Related topics

- [Laravel Fortify und Starter-Kits](/de/advanced/fortify.md)
- [Laravel-Updates April 2026](/de/blog/changelog/202604.md)
- [Migrations-Guide von laravel/ui zu Fortify](/de/blog/ui-to-fortify.md)
- [Laravel Chisel – Post-Install-Skript-Bibliothek für Starterkits](/de/blog/chisel-introduction.md)
- [Laravel LSP – IDE-Erweiterung per Language Server Protocol](/de/blog/laravel-lsp-introduction.md)