Passkeys – Einführung

Webfunktionen: Webauthentifizierung

Dieser Leitfaden bietet eine kompakte, handlungsorientierte Anleitung zur Implementierung einer sicheren, frameworkunabhängigen Passkey-Authentifizierung und Verwaltung von Anmeldedaten in modernen Webanwendungen.

1. Grundlegende Voraussetzungen für Passkeys

Passkeys basieren auf der Web Authentication API (WebAuthn), die strenge, übergreifende Sicherheitsanforderungen stellt, die vor jedem Implementierungsversuch erfüllt werden müssen:

  • Sichere Kontexte: WebAuthn-Methoden (navigator.credentials.create und navigator.credentials.get) sind nur in sicheren Kontexten verfügbar. Anwendungen MÜSSEN in der Produktion auf https:// oder für die lokale Entwicklung auf http://localhost ausgeführt werden.
  • Relying Party (RP) ID: Alle Anmeldedaten sind an eine RP-ID gebunden (im Wesentlichen der Domainname der Anwendung). Die in den serverseitigen Optionen übergebene RP-ID MUSS mit dem Domainnamen des aktuellen Ursprungs übereinstimmen oder ein gültiges Suffix davon sein (z.B. ist example.com für login.example.com gültig). Nichtübereinstimmungen führen zu SecurityError-Ausnahmen auf der Clientseite.

2. AAGUID-UX-Caveat

Die Authenticator Attestation Globally Unique Identifier (AAGUID) ist eine 128-Bit-Kennung, die in den Registrierungsbestätigungsdaten zurückgegeben wird und das Modell/den Anbieter des Authentifikators darstellt (z.B. Google Passwortmanager, iCloud-Schlüsselbund, 1Password).

  • Nur UX-Hinweise: Relying Parties MÜSSEN die AAGUID ausschließlich für UX-Hinweise verwenden (z. B. zum Rendern des Namens und Symbols des Passkey-Anbieters in einer Verwaltungsliste, um dem Nutzer zu helfen).
  • Keine Sicherheitsabhängigkeiten: Anwendungen DÜRFEN die AAGUID NICHT für kryptografische Sicherheits- oder Zugriffsentscheidungen verwenden. Plattform-Passkeys bieten derzeit keine kryptografische Attestierung für ihre AAGUIDs. Das bedeutet, dass sie von User-Agents geändert oder simuliert werden können.

3. Entkoppelte Bibliotheksempfehlungen

Für die Generierung von FIDO2-/WebAuthn-Optionen im Backend und die Signaturüberprüfung MÜSSEN Entwickler geprüfte Open-Source-Bibliotheken pro Sprache verwenden, anstatt die Kryptografie selbst zu implementieren:

  • JavaScript/TypeScript: SimpleWebAuthn (github.com/MasterKale/SimpleWebAuthn)
  • Python: py_webauthn (github.com/duo-labs/py_webauthn)
  • Java: Java WebAuthn Server (github.com/Yubico/java-webauthn-server), WebAuthn4J (github.com/webauthn4j/webauthn4j)
  • .NET: .NET-Bibliothek für FIDO2 (github.com/abergs/fido2-net-lib)
  • Go: WebAuthn Go-Bibliothek (github.com/go-webauthn/webauthn)
  • Ruby: WebAuthn Ruby (github.com/cedarcode/webauthn-ruby)
  • PHP: WebAuthn Framework (github.com/web-auth/webauthn-framework)

4. Referenzmatrix für Anwendungsfälle

Suchen Sie unten den passenden Anwendungsfall und rufen Sie den vollständigen Implementierungsleitfaden auf. Für jeden Anwendungsfall gibt es wichtige APIs (PublicKeyCredential.parseCreationOptionsFromJSON, parseRequestOptionsFromJSON, signalAllAcceptedCredentials, signalCurrentUserDetails, signalUnknownCredential, bedingte Vermittlung, AAGUID-Verarbeitung usw.), die nur in der Anleitung für den jeweiligen Anwendungsfall dokumentiert sind. Überspringen Sie diesen Abrufschritt NICHT und ersetzen Sie die Wrapper von Drittanbieterbibliotheken (z. B. startAuthentication/startRegistration von SimpleWebAuthn) auf dem Client NICHT. Rufen Sie die nativen WebAuthn-Browser-APIs direkt auf. Die Empfehlungen für Bibliotheken in Abschnitt 3 gelten nur für die serverseitige (FIDO2-Bestätigung im Backend).

Spezifische Details zur Implementierung von Passkeys und WebAuthn finden Sie in den folgenden Leitfäden: