Passkeys Cheat Sheet für Entwickler

Laden Sie das komplette Passkeys Cheat Sheet kostenlos herunter und erhalten Sie alle Einblicke.

• ✅ Bereits mehr als 4.000 Downloads
• ✅ Angefragt von Dev-Teams bei Ally, Kmart, Octopus Energy und Stanford CS
• ✅ Kein Marketing-Bla-Bla – nur technische Insights

Ultimativer Passkey-Entwickler-Leitfaden

Passkeys Cheat Sheet herunterladen

Holen Sie sich eine entwicklerorientierte Referenz für alles rund um Passkeys, einschließlich Plattformunterstützung, Browserverhalten, UX-Best-Practices und Integrationstipps.

Kostenloses Passkeys Cheat Sheet herunterladen

Geschäftliche E-Mail *

Name *

Unternehmen *

Position *

Kostenlos herunterladen

Die Authentifizierung mit Passkeys basiert auf den zwei Prozessen, auch Zeremonien (Ceremonies) genannt, Registrierung (auch Attestation-Phase) und Login (auch Assertion-Phase).
Jede Phase erfordert eine vom Server generierte zufällige Challenge, die vom Authenticator signiert und an den WebAuthn-Server zurückgesendet wird, um den Benutzer zu verifizieren.

Experimentieren Sie mit Passkey-Flows im Passkeys Debugger.

Kostenlos testen

Die Registrierungszeremonie verwendet zwei zentrale Objekte: PublicKeyCredentialCreationOptions und Attestation.

Die Login-Zeremonie verwendet zwei zentrale Objekte: PublicKeyCredentialRequestOptions und Assertion.

Sehen Sie, wie viele Menschen Passkeys tatsächlich nutzen.

Adoptionsdaten ansehen

Für die Registrierung und den Login mit Passkeys gibt es vier Hauptobjekte:

• PublicKeyCredentialCreationOptions
• PublicKeyCredentialRequestOptions
• attestation
• assertion

In diesem Abschnitt wird auch das Objekt authenticatorSelection erklärt, das in den PublicKeyCredentialCreationOptions verwendet wird.

Igor Gjorgjioski

Head of Digital Channels & Platform Enablement, VicRoads

We hit 80% mobile passkey activation across 5M+ users without replacing our IDP.

See how VicRoads scaled passkeys to 5M+ users — alongside their existing IDP.

Read the case study

PublicKeyCredentialCreationOptions ist das zentrale Objekt der Attestation-Phase (Registrierung). Es wird vom WebAuthn-Server erstellt und von diesem zurückgegeben.

{
    "PublicKeyCredentialCreationOptions": {
        "rp": {
            "id": "passkeys.eu",
            "name": "Corbado Passkeys Demo"
        },
        "user": {
            "displayName": "john.doe",
            "id": "dXNyLZ….DU10Tc",
            "name": "john@doe.com"
        },
        "challenge": "888fix4Bus...pHHr3Y",
        "pubKeyCredParams": [
            {
                "alg": -7,
                "type": "public-key"
            },
            {
                "alg": -257,
                "type": "public-key"
            }
        ],
        "excludeCredentials": [],
        "authenticatorSelection": {
            "authenticatorAttachment": "platform",
            "residentKey": "required",
            "userVerification": "required"
        },
        "attestation": "none",
        "extensions": {}
    }
}

Das Objekt enthält folgende Attribute:

• rp: Identifiziert die Relying Party (= den Server, der den Benutzer authentifizieren möchte), siehe Abschnitt 4.2 Relying Party ID (rpID).
• user: Enthält Daten über das Benutzerkonto, das die Attestation anfordert. Die ID ist eine von der Relying Party gewählte Bytekette, die keine persönlichen Informationen enthalten darf. Der Benutzername oder die E-Mail-Adresse wird stattdessen im Attribut name oder displayName gespeichert. Lesen Sie mehr dazu in Abschnitt 4.1 Datenbankschema.
• challenge: Eine zufällig generierte base64URL-kodierte BufferSource, die vom Authenticator signiert werden muss.
• pubKeyCredParams: Spezifische Attribute des zu erstellenden Credentials, in der Regel die unterstützten Algorithmen.
• timeout: Optionale Zeit in Millisekunden, die der Client auf den Abschluss des Aufrufs warten soll.
• excludeCredentials: Optionale Liste von Credentials, um die Erstellung mehrerer Passkeys auf einem Gerät zu begrenzen.
• authenticatorSelection: Optionale Auswahl des verwendeten Authenticators für die Methode, z. B. ob ein residentKey erforderlich ist. Siehe 2.5 authenticatorSelection.
• attestation: Kann verwendet werden, um anzufordern, dass das Attestation-Objekt in einer bestimmten Form an die Relying Party weitergegeben wird. Mögliche Werte sind none (Standard), indirect, direct und enterprise.
• extensions: Optionale Anfrage(n) für zusätzliche Verarbeitung, wie z. B. spezifische Rückgabewerte. z. B.
  • credProbs fordert Informationen darüber an, ob das erstellte Credential Discoverable (auffindbar) ist
  • prf ermöglicht der Relying Party die Verwendung von Ausgaben einer Pseudo-Random-Function (PRF), die mit einem Credential verknüpft ist

Abonnieren Sie unseren Passkeys Substack für aktuelle News.

Abonnieren

PublicKeyCredentialRequestOptions ist das zentrale Objekt der Assertion-Phase (Login). Es wird vom WebAuthn-Server erstellt und von diesem zurückgegeben.

{
    "publicKeyCredentialRequestOptions": {
        "challenge": "pT7HMA-…dFPHk",
        "timeout": 500,
        "rpId": "passkeys.eu",
        "userVerification": "preferred",
        "allowCredentials": [],
        "extensions": []
    }
}

Das Objekt enthält folgende Attribute:

• challenge, timeout, extensions: siehe oben.
• rpId: Die Kennung der Relying Party für die Assertion-Anforderung, siehe Abschnitt 4.2 Relying Party ID (rpID).
• allowCredentials: Optionale Liste von Credentials, die für die Authentifizierung zugelassen sind und die Präferenz des Aufrufers in absteigender Reihenfolge angeben. Diese Liste würde mit PublicKeyCredentialDescriptors gefüllt werden.
• userVerification: Optionaler Wert zur Angabe der Anforderungen an die Benutzerverifizierung während des Vorgangs. Mögliche Werte sind preferred (Standard), required oder discouraged.

Während der Attestation / Registrierungszeremonie gibt der Authenticator diese Registration Response zurück. Sie können dies selbst im Passkeys Debugger ausprobieren.

{
    "authenticatorAttachment": "platform",
    "id": "JKZbixUfKN_aZtimefYT-OjH5dw",
    "rawId": "JKZbixUfKN_aZtimefYT-OjH5dw",
    "response": {
        "attestationObject": {
            "fmt": "none",
            "attStmt": {},
            "authData": {
                "rpIdHash": "PpZrl-Wqt-OFfBpyy2SraN1m7LT0GZORwGA7-6ujYkM",
                "flags": {
                    "userPresent": true,
                    "userVerified": true,
                    "backupEligible": true,
                    "backupStatus": true,
                    "attestedData": true,
                    "extensionData": false
                },
                "counter": 0,
                "aaguid": {
                    "raw": "fbfc3007-154e-4ecc-8c0b-6e020557d7bd",
                    "name": "iCloud Keychain"
                },
                "credentialID": "JKZbixUfKN_aZtimefYT-OjH5dw",
                "credentialPublicKey": "pQECAyYgASFYIPWLalDzyxIDmAADvfK8iNM5To50kh7TyPH-teEz8RMdIlgg3D7bPIWQJ8z-WFn3zdYZzJw9c7mhPdmflQqD9vV7efA",
                "parsedCredentialPublicKey": {
                    "keyType": "EC2 (2)",
                    "algorithm": "ES256 (-7)",
                    "curve": 1,
                    "x": "9YtqUPPLEgOYAAO98ryI0zlOjnSSHtPI8f614TPxEx0",
                    "y": "3D7bPIWQJ8z-WFn3zdYZzJw9c7mhPdmflQqD9vV7efA"
                }
            }
        },
        "clientDataJSON": {
            "type": "webauthn.create",
            "challenge": "k2p6f-upzP_hc6NZvmMAxiI0VSTeQIeXXVRGW62LTj0",
            "origin": "https://www.passkeys-debugger.io",
            "crossOrigin": false
        },
        "transports": ["hybrid", "internal"],
        "authenticatorData": "PpZrl-Wqt-OFfBpyy2SraN1m7LT0GZORwGA7-6ujYkNdAAAAAPv8MAcVTk7MjAtuAgVX170AFCSmW4sVHyjf2mbYpnn2E_jox-XcpQECAyYgASFYIPWLalDzyxIDmAADvfK8iNM5To50kh7TyPH-teEz8RMdIlgg3D7bPIWQJ8z-WFn3zdYZzJw9c7mhPdmflQqD9vV7efA",
        "publicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE9YtqUPPLEgOYAAO98ryI0zlOjnSSHtPI8f614TPxEx3cPts8hZAnzP5YWffN1hnMnD1zuaE92Z-VCoP29Xt58A",
        "publicKeyAlgorithm": -7
    },
    "type": "public-key",
    "clientExtensionResults": {}
}

Die Attestation enthält einige wichtige Komponenten wie das attestationObject, den algorithm und die transport-Flags.

Entnommen aus der WebAuthn-Spezifikation des W3C

Das attestationObject ist ein CBOR-kodiertes Objekt, das Informationen über die neu erstellten Credentials, den öffentlichen Schlüssel (Public Key) und andere relevante Daten enthält:

• fmt wird für Passkeys typischerweise als "none" ausgewertet
• attStmt ist für Passkeys leer und für andere Authenticatoren gefüllt, z. B. Hardware-Sicherheitsschlüssel (Security Key)
• authData ist ein Puffer von Werten, der die folgenden Daten enthält:

Lesen Sie mehr über die Erweiterungen (Extensions).

Passkeys werden mit COSE-Algorithmen generiert, wobei der verwendete Algorithmus im algorithm-Attribut von parsedCredentialPublicKey im Attestation-Objekt angegeben ist.
Hier ist eine Übersicht der relevantesten COSE-Algorithmen:

Die Eigenschaft transports gibt die Mechanismen an, über die ein Authenticator mit einem Client kommunizieren kann. Einige gängige, beispielhafte Wertekombinationen sind:

• "transports": ["internal","hybrid"]: Passkeys können vom Plattform-Authenticator (z. B. Face ID, Touch ID, Windows Hello) oder über Cross-Device-Authentifizierung (mithilfe von QR-Code & Bluetooth) verwendet werden.
• "transports": ["internal"]: Passkeys können nur vom Plattform-Authenticator verwendet werden (z. B. Face ID, Touch ID, Windows Hello).
• Keine Eigenschaft "transports" festgelegt: Standardverhalten, das keine Hinweise liefert.

Während der Assertion / Login-Zeremonie gibt der Authenticator diese Login Response zurück. Sie können dies selbst im Passkeys Debugger ausprobieren.

{
    "id": "JKZbixUfKN_aZtimefYT-OjH5dw",
    "rawId": "JKZbixUfKN_aZtimefYT-OjH5dw",
    "type": "public-key",
    "authenticatorAttachment": "platform",
    "response": {
        "authenticatorData": {
            "rpIdHash": "PpZrl-Wqt-OFfBpyy2SraN1m7LT0GZORwGA7-6ujYkM",
            "flags": {
                "userPresent": true,
                "userVerified": true,
                "backupEligible": true,
                "backupStatus": true,
                "attestedData": false,
                "extensionData": false
            },
            "counter": 0
        },
        "clientDataJSON": {
            "type": "webauthn.get",
            "challenge": "GCVkITWbe2l2dttsn_DgJYvH9QPHPDo0ygWgcgI6B7U",
            "origin": "https://www.passkeys-debugger.io",
            "crossOrigin": false,
            "other_keys_can_be_added_here": "do not compare clientDataJSON against a template. See https://goo.gl/yabPex"
        },
        "signature": "MEQCIA-orC8N2KKWOxyY17BWP8lB-Be5to9btXRnJZf2SLhXAiBGxJe5Eu5LwOTbsyzAYmIXHOhlC3pN7s7Q1fRLvEW57g",
        "userHandle": "_FKz1uwqmR_3yGq6hJntzoIFwFC_d1u_53YRELh0KlE"
    }
}

Die Assertion enthält einige wichtige Komponenten wie Flags, Signatur und userHandle.

Hier ist eine Übersicht der wichtigsten Flags und ihrer Kombinationen:

Die Signatur wird verwendet, um zu verifizieren, dass der Benutzer, der versucht sich anzumelden, tatsächlich den privaten Schlüssel (Private Key) besitzt. Die Signatur wird erstellt, indem die authenticatorData und der clientDataHash (d. h. die SHA-256-Version des ClientDataJSON) verkettet werden und das Ergebnis mit dem privaten Schlüssel (im Authenticator) signiert wird. Zur Verifizierung mit dem öffentlichen Schlüssel verketten wir ebenfalls authenticatorData und clientDataHash. Wenn das Verifizierungsergebnis wahr zurückgibt, ist die Authentifizierung erfolgreich.

Der userHandle ist die eigentliche user_id. Lesen Sie mehr über die user_id im Abschnitt 4.1 Datenbankschema.

Das Objekt authenticatorSelection ermöglicht es dem Server, Einstellungen für den Authenticator und die Erstellung von Credentials mit den folgenden Werten vorzuschreiben:

• Platform: Der Authenticator ist an die Plattform des Clients gebunden und daher nicht abnehmbar.
• Cross-platform: Der Authenticator ist nicht an die Plattform des Clients gebunden und kann auf mehreren Geräten verwendet werden.

• Required: Der Authenticator muss einen Resident Key erstellen (falls nicht möglich, sollte die Operation fehlschlagen).
• Preferred: Der Authenticator sollte versuchen, einen Resident Key zu erstellen (falls nicht möglich, sollte er einen Non-Resident Key erstellen).
• Discouraged: Der Authenticator muss einen Non-Resident Key erstellen (falls nicht möglich, sollte die Operation fehlschlagen).

• Required: Der Vorgang sollte den Benutzer verifizieren.
• Preferred: Der Vorgang sollte den Benutzer verifizieren, kann jedoch ohne diese Verifizierung fortgesetzt werden (Standardoption).
• Discouraged: Der Vorgang sollte den Benutzer nicht verifizieren.

Conditional UI (Passkey-Autofill) zeigt dem Benutzer verfügbare Passkeys in einem Auswahl-Dropdown an, wenn ein Benutzer einen Resident Key bei der Relying Party registriert hat. Es verbessert die Benutzerfreundlichkeit von Passkeys, erfordert jedoch zusätzliche Entwicklungsaufwände und ist nicht für alle OS / Browser-Kombinationen verfügbar.

Wie bei einem regulären Login verwendet Conditional UI auch die Objekte PublicKeyCredentialRequestOptions und Assertion.

Conditional UI ist (noch) nicht auf allen Kombinationen von Betriebssystemen und Browsern verfügbar. Hier ist ein Überblick über die aktuelle Browserabdeckung (März 2024):

Für eine aktuelle Übersicht siehe diese Website.

Ein vollständiger, minimalistischer Code für eine Conditional UI-Methode sieht so aus:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>Conditional UI</title>
    </head>
    <body>
        <input type="text" id="username" autocomplete="username webauthn" />
 
        <script>
            async function passkeyLogin() {
                try {
                    // retrieve the request options (incl. the challenge) from the WebAuthn server
                    let options = await WebAuthnClient.getPublicKeyRequestOptions();
 
                    const credential = await navigator.credentials.get({
                        publicKey: options.publicKeyCredentialRequestOptions,
                        mediation: "conditional",
                    });
 
                    const userData = await WebAuthnClient.sendSignedChallenge(credential);
                    window.location.href = "/logged-in";
                } catch (error) {
                    console.log(error);
                }
            }
 
            passkeyLogin();
        </script>
    </body>
</html>

Conditional UI funktioniert nur mit Resident Keys / Discoverable Credentials.
Es wird empfohlen, einen anderen Server-Endpunkt bereitzustellen, um den Conditional UI-Login zu starten.
Der Client muss mehrere Anforderungen erfüllen:

• Der Browser muss Conditional UI unterstützen (siehe 3.2 Gerätekompatibilität).
• JavaScript muss aktiviert sein und die Webseite muss ein HTML-Eingabefeld bereitstellen.
• Timeout-Parameter sollten ignoriert werden.

Um Fehler zu vermeiden, sollte der Server zuerst die Verfügbarkeit des Clients mit dieser Funktion testen: Im realen Datenverkehr treten Erkennungs- und Lebenszyklusprobleme oft als NotAllowedError oder AbortError auf. Nutzen Sie diesen WebAuthn-Fehler-Leitfaden für die Klassifizierung in erwartete vs. unerwartete Fehler, einschließlich nativer Credential Manager Passkey-Fehler.

// source: https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredential/isConditionalMediationAvailable#examples
 
// Availability of `window.PublicKeyCredential` means WebAuthn is usable.
if (window.PublicKeyCredential && PublicKeyCredential.isConditionalMediationAvailable) {
    // Check if conditional mediation is available.
    const isCMA = await PublicKeyCredential.isConditionalMediationAvailable();
    if (isCMA) {
        // Call WebAuthn authentication start endpoint
 
        let options = await WebAuthnClient.getPublicKeyRequestOptions();
 
        const credential = await navigator.credentials.get({
            publicKey: options.publicKeyCredentialRequestOptions,
            mediation: "conditional",
        });
        /*
    ...
    */
    }
}

Das Eingabefeld sollte ein HTML-Autofill-Token erhalten, das dem Client signalisiert, Passkeys für die laufende Anfrage auszufüllen. Neben Passkeys können die Autofill-Token mit vorhandenen Token kombiniert werden, z. B. Benutzernamen und Passwörtern:

• autocomplete="username webauthn": Zeigt nicht nur Passkeys an, sondern schlägt auch das automatische Ausfüllen des Benutzernamens vor.
• autocomplete="current-password webauthn": Zeigt nicht nur Passkeys an, sondern fordert außerdem zum automatischen Ausfüllen des Passworts auf.

<label for="name">Username:</label>
<input type="text" name="name" autocomplete="username webauthn" />
<label for="password">Password:</label>
<input type="password" name="password" autocomplete="current-password webauthn" />

Es gibt kein obligatorisches oder standardisiertes Datenbankschema für WebAuthn-Server. Dieses beispielhafte Datenbankschema kann jedoch verwendet werden, um die erforderlichen Informationen zu speichern und alle Funktionen eines WebAuthn-Servers bereitzustellen:

Fett gedruckte Attribute sind für eine minimal funktionsfähige Implementierung obligatorisch, während die anderen nur für optionale, aber hilfreiche Funktionen benötigt werden.

• Credential ID: Dies ist eine eindeutige ID, die vom Authenticator während der Registrierung eines Passkeys generiert wird. Sie sollte verwendet werden, um das tatsächliche Benutzerkonto nachzuschlagen, das mit dem Passkey verknüpft ist. Zusätzlich sollte dann der userHandle (von user_id) verglichen werden, um das für die Authentifizierung verwendete Konto zu validieren. Verwenden Sie das Attribut user.name nicht für Vergleiche, da es sich im Laufe der Zeit ändern kann.
• User ID (user_id): Eine von der Relying Party festgelegte eindeutige ID, um ein Benutzerkonto in ihrem System darzustellen. Sie wird als userHandle innerhalb des Assertion-Objekts zurückgegeben.

• User DisplayName (user.displayName): Benutzerfreundlicher, lesbarer Name, der normalerweise der vollständige Name des Benutzers ist. Er wird dem Benutzer angezeigt, jedoch nicht während der Authentifizierung verwendet.

• User Name (user.name): Eindeutiger und lesbarer Name, der normalerweise eine E-Mail-Adresse oder ein Benutzername ist. Er kann dem Benutzer angezeigt werden, wird jedoch nicht während der Authentifizierung verwendet.

Die Relying Party ID (rpID) ist eine Domäne, die innerhalb des Passkeys gespeichert ist und sicherstellt, dass der Passkey nur für die korrekte Domäne funktioniert (Browser-URL, siehe diesen Artikel für native Apps). Während der Authentifizierung wird die rpID gegen die Browser-URL geprüft und nur in diesen beiden Fällen zugelassen:

1. Die URL stimmt exakt mit der rpId überein ODER
2. Die URL ist eine Subdomain, die mit der rpId übereinstimmt, und die übergeordnete Domain steht nicht auf der Public Suffix List.

Hier sind Beispiele für (un-)zulässige Kombinationen:

Hier ist eine Liste nützlicher Tools & Websites zur Implementierung von Passkeys.

• Passkeys Debugger: Tool zum Debuggen der WebAuthn Responses als JSON und zum Testen von WebAuthn-Operationen mit verschiedenen Optionen.
• Passkeys Glossar: Erklärung von Begriffen & Konzepten rund um Passkeys.
• WebAuthn-Spezifikation: Dies ist die offizielle WebAuthn-Spezifikation.
• Chrome Device Log: Tool zur Anzeige eines Protokolls der WebAuthn-Operationen Ihres Geräts (nur in Chrome über chrome://device-log verfügbar).

Für Strategien zur Optimierung Ihrer Passkey-UX über die technische Implementierung hinaus, lesen Sie unsere Leitfäden zu Best Practices für die Passkey-Erstellung und Best Practices für den Passkey-Login.

Wenn Sie Passkeys mit nur wenigen Codezeilen in eine beliebige Anwendung implementieren möchten, können Sie auch Corbado Complete (für neue Apps) oder Corbado Connect (für bestehende Apps) verwenden.

Über Corbado

Corbado ist die Authentication Intelligence Platform für CIAM-Teams, die Consumer-Authentifizierung im großen Maßstab betreiben. Wir zeigen Ihnen, was IDP-Logs und generische Analytics-Tools nicht sehen können: welche Geräte, OS-Versionen, Browser und Credential-Manager Passkeys unterstützen, warum Enrollments nicht zu Logins werden, wo der WebAuthn-Flow scheitert und wann ein OS- oder Browser-Update den Login still und leise unterbricht – und das alles, ohne Okta, Auth0, Ping, Cognito oder Ihren In-House-IDP zu ersetzen. Zwei Produkte: Corbado Observe ergänzt Observability für Passkeys und jede andere Login-Methode. Corbado Connect bringt Managed Passkeys mit integrierter Analytics (neben Ihrem IDP). VicRoads betreibt Passkeys für über 5 Mio. Nutzer mit Corbado (+80 % Passkey-Aktivierung). Mit einem Passkey-Experten sprechen →

Conditional UI erfordert eine Überprüfung der Browser-Unterstützung über PublicKeyCredential.isConditionalMediationAvailable(), bevor die Authentifizierung initiiert wird. Das Eingabefeld muss das HTML-Token autocomplete="username webauthn" enthalten und der Benutzer muss über einen registrierten Resident Key (Discoverable Credential) verfügen. Es wird ein separater Server-Endpunkt empfohlen, um den Conditional UI-Login-Ablauf abzuwickeln.

Speichern Sie mindestens die Credential ID, die während der Registrierung vom Authenticator generiert wurde, und die User ID (user_id), die als userHandle im Assertion-Objekt zurückgegeben wird. Verwenden Sie die Credential ID, um das zugehörige Benutzerkonto nachzuschlagen, und vergleichen Sie den userHandle, um die Authentifizierung zu validieren. Vermeiden Sie die Verwendung von user.name für Vergleiche, da sich dieser im Laufe der Zeit ändern kann.

Resident Keys (Discoverable Credentials) werden auf dem Authenticator selbst gespeichert und während der Authentifizierung abgerufen. Dies ist erforderlich, damit Conditional UI funktioniert. Bei Non-Resident Keys wird die Credential ID auf dem Server gespeichert und während der Authentifizierung an den Authenticator gesendet. Das Feld residentKey in authenticatorSelection steuert dieses Verhalten mit den Werten "required", "preferred" oder "discouraged".

Das Feld userVerification steuert, ob der Authenticator den Benutzer während der Anmeldung verifizieren muss. Die möglichen Werte sind "required", "preferred" (Standard) oder "discouraged". Wenn der Wert auf "preferred" gesetzt ist, können der Benutzer oder sein Gerät die Überprüfung während des Authentifizierungsprozesses vollständig überspringen, was die Sicherheit schwächen kann. Durch die Einstellung auf "required" wird sichergestellt, dass die Überprüfung immer erfolgt, bevor die Authentifizierung abgeschlossen ist.