Passkey für Anmeldungen ohne Passwort erstellen

Passkeys machen Nutzerkonten sicherer, einfacher und nutzerfreundlicher.

Eiji Kitamura

Die Verwendung von Passkeys anstelle von Passwörtern ist eine gute Möglichkeit für Websites, ihre Nutzerkonten sicherer, einfacher, nutzerfreundlicher und passwortlos zu machen. Mit einem Passkey kann sich ein Nutzer mit seinem Fingerabdruck, seinem Gesicht oder der PIN seines Geräts auf einer Website oder in einer App anmelden.

Sie müssen einen Passkey erstellen, mit einem Nutzerkonto verknüpfen und seinen öffentlichen Schlüssel auf Ihrem Server speichern, bevor sich ein Nutzer damit anmelden kann.

Funktionsweise

In den folgenden Fällen werden Nutzer möglicherweise aufgefordert, einen Passkey zu erstellen:

• Ein Nutzer meldet sich mit einem Passwort an.
• Wenn sich ein Nutzer mit einem Passkey von einem anderen Gerät anmeldet (d. h., authenticatorAttachment ist cross-platform).
• Auf einer speziellen Seite, auf der Nutzer ihre Passkeys verwalten können.

Zum Erstellen eines Passkeys verwenden Sie die WebAuthn API.

Die vier Komponenten der Passkey-Registrierung sind:

• Back-End: Ihr Back-End-Server, auf dem sich die Kontendatenbank befindet, in der der öffentliche Schlüssel und andere Metadaten zum Passkey gespeichert sind.
• Frontend: Das Frontend, das mit dem Browser kommuniziert und Abrufanfragen an das Backend sendet.
• Browser: Der Browser des Nutzers, in dem Ihr JavaScript ausgeführt wird.
• Authenticator: Der Authenticator des Nutzers, der den Passkey erstellt und speichert. Dazu kann der Passwortmanager auf demselben Gerät wie der Browser (z. B. bei Verwendung von Windows Hello) oder auf einem anderen Gerät wie einem Smartphone gehören.

So fügen Sie einem vorhandenen Nutzerkonto einen neuen Passkey hinzu:

1. Ein Nutzer meldet sich auf der Website an.
2. Nachdem sich der Nutzer angemeldet hat, kann er auf der Frontend-Seite einen Passkey erstellen, z. B. durch Drücken der Schaltfläche „Passkey erstellen“.
3. Das Frontend fordert Informationen vom Backend an, um einen Passkey zu erstellen, z. B. Nutzerinformationen, eine Herausforderung und die Anmeldedaten-IDs, die ausgeschlossen werden sollen.
4. Das Front-End ruft navigator.credentials.create() auf, um einen Passkey zu erstellen. Dieser Aufruf gibt ein Versprechen zurück.
5. Ein Passkey wird erstellt, nachdem der Nutzer der Verwendung der Displaysperre des Geräts zugestimmt hat. Das Promise wird aufgelöst und die Anmeldedaten mit einem öffentlichen Schlüssel werden an das Front-End zurückgegeben.
6. Das Front-End sendet die Anmeldedaten mit öffentlichem Schlüssel an das Back-End und speichert die Anmeldedaten-ID und den öffentlichen Schlüssel, die dem Nutzerkonto zugeordnet sind, für zukünftige Authentifizierungen.

Kompatibilitäten

WebAuthn wird von den meisten Browsern unterstützt, es gibt jedoch kleine Lücken. Unter Gerätesupport – Passkeyss.dev erfahren Sie, welche Kombination aus Browsern und Betriebssystemen das Erstellen eines Passkeys unterstützt.

Neuen Passkey erstellen

So sollte ein Frontend auf eine Anfrage zum Erstellen eines neuen Passkeys reagieren:

Funktionserkennung

Bevor die Schaltfläche „Neuen Passkey erstellen“ angezeigt wird, muss Folgendes erfüllt sein:

• Der Browser unterstützt WebAuthn mit PublicKeyCredential.

• Das Gerät unterstützt einen Plattform-Authentifikator (kann einen Passkey erstellen und sich damit authentifizieren) mit PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable().

• Der Browser unterstützt die bedingte WebAuthn-UI mit PublicKeyCredenital.isConditionalMediationAvailable().

// Availability of `window.PublicKeyCredential` means WebAuthn is usable.  
// `isUserVerifyingPlatformAuthenticatorAvailable` means the feature detection is usable.  
// `​​isConditionalMediationAvailable` means the feature detection is usable.  
if (window.PublicKeyCredential &&  
    PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable &&  
    PublicKeyCredential.​​isConditionalMediationAvailable) {  
  // Check if user verifying platform authenticator is available.  
  Promise.all([  
    PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable(),  
    PublicKeyCredential.​​isConditionalMediationAvailable(),  
  ]).then(results => {  
    if (results.every(r => r === true)) {  
      // Display "Create a new passkey" button  
    }  
  });  
}  

Solange nicht alle Bedingungen erfüllt sind, werden Passkeys in diesem Browser nicht unterstützt. Bis dahin sollte die Schaltfläche „Neuen Passkey erstellen“ nicht angezeigt werden.

Wichtige Informationen aus dem Backend abrufen

Wenn der Nutzer auf die Schaltfläche klickt, werden wichtige Informationen abgerufen, um navigator.credentials.create() aus dem Backend aufzurufen:

• challenge: Eine servergenerierte Herausforderung in ArrayBuffer für diese Registrierung. Diese Angabe ist erforderlich, wird aber bei der Registrierung nicht verwendet, es sei denn, Sie führen eine Attestierung durch. Dies ist ein fortgeschrittenes Thema, das hier nicht behandelt wird.
• user.id: Die eindeutige ID eines Nutzers. Dieser Wert muss ein ArrayBuffer sein, der keine personenidentifizierbaren Informationen wie E-Mail-Adressen oder Nutzernamen enthält. Ein zufälliger Wert von 16 Byte, der pro Konto generiert wird, ist gut geeignet.
• user.name: Dieses Feld sollte eine eindeutige Kennung für das Konto enthalten, die der Nutzer erkennt, z. B. seine E-Mail-Adresse oder seinen Nutzernamen. Dieser wird in der Kontoauswahl angezeigt. (Wenn Sie einen Nutzernamen verwenden, verwenden Sie denselben Wert wie bei der Passwortauthentifizierung.)
• user.displayName: Dies ist ein erforderlicher, nutzerfreundlicherer Name für das Konto. Er muss nicht eindeutig sein und kann der vom Nutzer ausgewählte Name sein. Wenn Ihre Website keinen geeigneten Wert enthält, geben Sie einen leeren String an. Je nach Browser wird diese Option möglicherweise in der Kontoauswahl angezeigt.
• excludeCredentials: Verhindert die Registrierung desselben Geräts, indem eine Liste bereits registrierter Anmeldedaten-IDs zur Verfügung gestellt wird. Das Mitglied transports sollte, falls angegeben, das Ergebnis des Aufrufs von getTransports() während der Registrierung der einzelnen Anmeldedaten enthalten.

WebAuthn API aufrufen, um einen Passkey zu erstellen

Rufen Sie navigator.credentials.create() auf, um einen neuen Passkey zu erstellen. Die API gibt ein Versprechen zurück, das auf die Interaktion des Nutzers wartet und ein modales Dialogfeld anzeigt.

const publicKeyCredentialCreationOptions = {
  challenge: *****,
  rp: {
    name: "Example",
    id: "example.com",
  },
  user: {
    id: *****,
    name: "john78",
    displayName: "John",
  },
  pubKeyCredParams: [{alg: -7, type: "public-key"},{alg: -257, type: "public-key"}],
  excludeCredentials: [{
    id: *****,
    type: 'public-key',
    transports: ['internal'],
  }],
  authenticatorSelection: {
    authenticatorAttachment: "platform",
    requireResidentKey: true,
  }
};

const credential = await navigator.credentials.create({
  publicKey: publicKeyCredentialCreationOptions
});

// Encode and send the credential to the server for verification.  

Die oben nicht beschriebenen Parameter sind:

• rp.id: Eine RP-ID ist eine Domain und eine Website kann entweder ihre Domain oder ein registrierbares Suffix angeben. Wenn der Ursprung eines RP beispielsweise https://login.example.com:1337 ist, kann die RP-ID entweder login.example.com oder example.com sein. Wenn die RP-ID als example.com angegeben ist, kann sich der Nutzer bei login.example.com oder auf einer beliebigen Subdomain von login.example.com authentifizieren.

• rp.name: Name des RP.

• pubKeyCredParams: In diesem Feld werden die unterstützten Public-Key-Algorithmen des RP angegeben. Wir empfehlen, hier [{alg: -7, type: "public-key"},{alg: -257, type: "public-key"}] festzulegen. Damit wird die Unterstützung von ECDSA mit P-256 und RSA PKCS#1 angegeben. Die Unterstützung dieser beiden Verfahren bietet eine vollständige Abdeckung.

• authenticatorSelection.authenticatorAttachment: Legen Sie diesen Wert auf "platform" fest, wenn die Erstellung dieses Passkeys ein Upgrade von einem Passwort ist, z. B. in einer Werbeaktion nach einer Anmeldung. "platform" gibt an, dass die RP einen Plattform-Authenticator (einen in das Plattformgerät eingebetteten Authenticator) benötigt, der nicht auffordert, z.B. einen USB-Sicherheitsschlüssel einzufügen. Der Nutzer hat eine einfachere Möglichkeit, einen Passkey zu erstellen.

• authenticatorSelection.requireResidentKey: Legen Sie den Wert auf „true“ fest. In einem Anmeldedatensatz, der gefunden werden kann (Resident Key), werden Nutzerinformationen im Passkey gespeichert und Nutzer können das Konto bei der Authentifizierung auswählen. Weitere Informationen zu Anmeldedaten, die für andere sichtbar sind

• authenticatorSelection.userVerification: Gibt an, ob eine Nutzerbestätigung über die Displaysperre des Geräts "required", "preferred" oder "discouraged" ist. Die Standardeinstellung ist "preferred". Das bedeutet, dass der Authenticator die Nutzerbestätigung möglicherweise überspringt. Legen Sie dafür "preferred" fest oder lassen Sie das Attribut weg.

Die zurückgegebenen Public-Key-Anmeldedaten an das Backend senden

Nachdem der Nutzer über die Displaysperre des Geräts seine Einwilligung erteilt hat, wird ein Passkey erstellt und das Versprechen wird erfüllt, indem ein PublicKeyCredential-Objekt an das Frontend zurückgegeben wird.

Das Versprechen kann aus verschiedenen Gründen abgelehnt werden. Zur Behebung dieser Fehler müssen Sie das Attribut name des Error-Objekts prüfen:

• InvalidStateError: Auf dem Gerät ist bereits ein Passkey vorhanden. Dem Nutzer wird kein Fehlerdialogfeld angezeigt und die Website sollte dies nicht als Fehler behandeln. Der Nutzer wollte, dass das lokale Gerät registriert wird, und das ist der Fall.
• NotAllowedError: Der Nutzer hat den Vorgang abgebrochen.
• Andere Ausnahmen: Ein unerwarteter Fehler ist aufgetreten. Im Browser wird dem Nutzer ein Fehlerdialogfeld angezeigt.

Das Objekt „Public-Key-Anmeldedaten“ enthält die folgenden Eigenschaften:

• id: Eine Base64URL-codierte ID des erstellten Passkeys. Anhand dieser ID kann der Browser bei der Authentifizierung feststellen, ob sich auf dem Gerät ein übereinstimmender Passkey befindet. Dieser Wert muss in der Datenbank im Backend gespeichert werden.
• rawId: Eine ArrayBuffer-Version der Anmeldedaten-ID.
• response.clientDataJSON: Ein ArrayBuffer-codierte Kundendaten.
• response.attestationObject: Ein ArrayBuffer-codiertes Attestierungsobjekt. Diese enthält wichtige Informationen wie eine RP-ID, Flags und einen öffentlichen Schlüssel.
• authenticatorAttachment: Wird "platform" zurückgegeben, wenn diese Anmeldedaten auf einem Gerät mit Passkey erstellt wurden.
• type: Dieses Feld ist immer auf "public-key" gesetzt.

Wenn Sie eine Bibliothek zum Verwalten des Public-Key-Anmeldedatenobjekts im Backend verwenden, empfehlen wir, das gesamte Objekt an das Backend zu senden, nachdem es teilweise mit base64url codiert wurde.

Anmeldedaten speichern

Wenn du die Anmeldedaten für den öffentlichen Schlüssel im Backend erhältst, gib sie an die FIDO-Bibliothek weiter, um das Objekt zu verarbeiten.

Sie können die aus den Anmeldedaten abgerufenen Informationen dann zur späteren Verwendung in der Datenbank speichern. Die folgende Liste enthält einige typische Eigenschaften, die Sie speichern sollten:

• Anmeldedaten-ID (Primärschlüssel)
• Nutzer-ID
• Öffentlicher Schlüssel

Die Anmeldedaten mit öffentlichem Schlüssel enthalten außerdem die folgenden Informationen, die Sie in der Datenbank speichern möchten:

• Flag für die Back-up-Berechtigung:true, wenn das Gerät für die Passkey-Synchronisierung infrage kommt.
• Flag für den Sicherungsstatus: true Gibt an, ob der erstellte Passkey tatsächlich für die Synchronisierung eingerichtet ist.
• Transports: Liste der vom Gerät unterstützten Transports: "internal" bedeutet, dass das Gerät einen Passkey unterstützt, "hybrid" bedeutet, dass es auch die Authentifizierung auf einem anderen Gerät unterstützt.

Eine ausführlichere Anleitung finden Sie unter Serverseitige Passkey-Registrierung.

Informationen zur Authentifizierung des Nutzers finden Sie unter Über das automatische Ausfüllen von Formularen mit einem Passkey anmelden.

Ressourcen

• Serverseitige Passkey-Registrierung
• Über das automatische Ausfüllen von Formularen mit einem Passkey anmelden
• Passkeys
• Apple-Dokument: Nutzer über einen Webdienst authentifizieren
• Google-Dokument: Passwortlose Anmeldung mit Passkeys