Übersicht
Hier ist eine Übersicht über die wichtigsten Schritte bei der Passkey-Registrierung:

- Definieren Sie Optionen zum Erstellen eines Passkeys. Senden Sie sie an den Client, damit Sie sie an den Aufruf zur Passkey-Erstellung weitergeben können: den WebAuthn API-Aufruf
navigator.credentials.createim Web undcredentialManager.createCredentialauf Android-Geräten. Nachdem der Nutzer die Erstellung des Passkeys bestätigt hat, wird der Aufruf zur Passkey-Erstellung aufgelöst und einPublicKeyCredential-Anmeldedatenobjekt zurückgegeben. - Überprüfen Sie die Anmeldedaten und speichern Sie sie auf dem Server.
In den folgenden Abschnitten werden die einzelnen Schritte genauer beschrieben.
Optionen zum Erstellen von Anmeldedaten erstellen
Der erste Schritt auf dem Server besteht darin, ein PublicKeyCredentialCreationOptions-Objekt zu erstellen.
Verwenden Sie dazu Ihre serverseitige FIDO-Bibliothek. In der Regel wird eine Dienstfunktion angeboten, mit der Sie diese Optionen erstellen können. SimpleWebAuthn bietet beispielsweise generateRegistrationOptions.
PublicKeyCredentialCreationOptions sollte alles enthalten, was für die Passkey-Erstellung erforderlich ist: Informationen zum Nutzer, zur vertrauenden Partei und eine Konfiguration für die Attribute der zu erstellenden Anmeldedaten. Nachdem Sie alle diese Werte definiert haben, übergeben Sie sie nach Bedarf an die Funktion in Ihrer serverseitigen FIDO-Bibliothek, die für das Erstellen des PublicKeyCredentialCreationOptions-Objekts verantwortlich ist.
Einige Felder von PublicKeyCredentialCreationOptions können Konstanten sein. Andere sollten dynamisch auf dem Server definiert werden:
rpId: Verwenden Sie zum Ausfüllen der RP-ID auf dem Server serverseitige Funktionen oder Variablen, die den Hostnamen Ihrer Webanwendung angeben, z. B.example.com.user.nameunduser.displayName: Verwende die Sitzungsinformationen des angemeldeten Nutzers, um diese Felder zu füllen. Wenn der Nutzer bei der Registrierung einen Passkey erstellt, verwende die Informationen des neuen Nutzerkontos.user.nameist in der Regel eine E-Mail-Adresse und für die vertrauende Seite eindeutig.user.displayNameist ein nutzerfreundlicher Name. Beachten Sie, dass nicht alle PlattformendisplayNameverwenden.user.id: Ein zufälliger, eindeutiger String, der bei der Kontoerstellung generiert wird. Sie sollte dauerhaft sein, im Gegensatz zu einem Nutzernamen, der möglicherweise bearbeitet werden kann. Die Nutzer-ID identifiziert ein Konto, darf aber keine personenidentifizierbaren Informationen enthalten. Wahrscheinlich haben Sie bereits eine Nutzer-ID in Ihrem System. Erstellen Sie bei Bedarf jedoch eine speziell für Passkeys, damit sie keine personenidentifizierbaren Informationen enthält.excludeCredentials: Eine Liste der IDs vorhandener Anmeldedaten, um zu verhindern, dass ein Passkey vom Passkey-Anbieter dupliziert wird. Suchen Sie in Ihrer Datenbank nach vorhandenen Anmeldedaten für diesen Nutzer, um dieses Feld auszufüllen. Weitere Informationen finden Sie unter Erstellung eines neuen Passkeys verhindern, wenn bereits einer vorhanden ist.challenge: Bei der Registrierung von Anmeldedaten ist die Challenge nur relevant, wenn Sie die Attestierung verwenden, eine erweiterte Technik zur Überprüfung der Identität eines Passkey-Anbieters und der von ihm ausgegebenen Daten. Auch wenn Sie die Attestierung nicht verwenden, ist die Challenge ein Pflichtfeld. Eine Anleitung zum Erstellen einer sicheren Challenge für die Authentifizierung finden Sie unter Serverseitige Passkey-Authentifizierung.
Codierung und Decodierung
PublicKeyCredentialCreationOptions, die vom Server gesendet wird. Binäre Felder wie challenge und user.id werden serverseitig in base64URL codiert, damit Optionen als JSON über HTTPS bereitgestellt werden können.Das standardmäßige WebAuthn-PublicKeyCredentialCreationOptions-Objekt enthält Felder, die ArrayBuffers sind und nicht direkt mit JSON.stringify() serialisiert werden können. Wenn Sie diese Optionen über HTTPS senden möchten, müssen binäre Felder als base64URL-Strings codiert werden:
- Auf dem Server: Ihre serverseitige FIDO-Bibliothek (z. B. SimpleWebAuthn) erzeugt automatisch ein JSON-serialisierbares Optionsobjekt (z. B.
PublicKeyCredentialCreationOptionsJSON) mit Base64URL-codierten Feldern. - Auf dem Client unterstützen moderne Browser
PublicKeyCredential.parseCreationOptionsFromJSON(), um die JSON-Optionen direkt inPublicKeyCredentialCreationOptionszu konvertieren. Wenn Sie clientseitige Bibliotheken wie@simplewebauthn/browserverwenden, wird diese Konvertierung automatisch von Funktionen wiestartRegistration({ optionsJSON: options })durchgeführt.
Beispielcode: Optionen zum Erstellen von Anmeldedaten erstellen
In unseren Beispielen verwenden wir die SimpleWebAuthn-Bibliothek. Hier übergeben wir die Erstellung der Optionen für die Anmeldedaten für den öffentlichen Schlüssel an die Funktion generateRegistrationOptions.
import {
generateRegistrationOptions,
verifyRegistrationResponse,
} from '@simplewebauthn/server';
import { isoBase64URL, isoUint8Array } from '@simplewebauthn/server/helpers';
router.post('/registerRequest', csrfCheck, sessionCheck, async (req, res) => {
const { user } = res.locals;
// Ensure you nest verification function calls in try/catch blocks.
// If something fails, throw an error with a descriptive error message.
// Return that message with an appropriate error code to the client.
try {
// `excludeCredentials` prevents users from re-registering existing
// credentials for a given passkey provider
const excludeCredentials = [];
const credentials = Credentials.findByUserId(user.id);
if (credentials.length > 0) {
for (const cred of credentials) {
excludeCredentials.push({
id: cred.id,
type: 'public-key',
transports: cred.transports,
});
}
}
// Generate registration options for WebAuthn create
const options = await generateRegistrationOptions({
rpName: process.env.RP_NAME,
rpID: process.env.HOSTNAME,
userID: isoUint8Array.fromUTF8String(user.id),
userName: user.username,
userDisplayName: user.displayName || '',
attestationType: 'none',
excludeCredentials,
authenticatorSelection: {
authenticatorAttachment: 'platform',
residentKey: 'required',
userVerification: 'preferred',
},
});
// Keep the challenge in the session
req.session.challenge = options.challenge;
return res.json(options);
} catch (e) {
console.error(e);
return res.status(400).send({ error: e.message });
}
});
Öffentlichen Schlüssel speichern
navigator.credentials.create gibt ein PublicKeyCredential-Objekt zurück.Wenn navigator.credentials.create auf dem Client erfolgreich aufgelöst wird, bedeutet das, dass ein Passkey erstellt wurde. Ein PublicKeyCredential-Objekt wird zurückgegeben.
Das PublicKeyCredential-Objekt enthält ein AuthenticatorAttestationResponse-Objekt, das die Antwort des Passkey-Anbieters auf die Anweisung des Clients zum Erstellen eines Passkeys darstellt. Sie enthält Informationen zu den neuen Anmeldedaten, die Sie als RP benötigen, um den Nutzer später zu authentifizieren. Weitere Informationen zu AuthenticatorAttestationResponse finden Sie im Anhang: AuthenticatorAttestationResponse.
Senden Sie das PublicKeyCredential-Objekt an den Server. Bestätigen Sie den Erhalt.
Übergeben Sie diesen Verifizierungsschritt an Ihre serverseitige FIDO-Bibliothek. In der Regel wird dafür eine Dienstfunktion angeboten. SimpleWebAuthn bietet beispielsweise verifyRegistrationResponse. Weitere Informationen dazu, was im Hintergrund passiert, finden Sie im Anhang: Verifizierung der Registrierungsantwort.
Nachdem die serverseitige FIDO-Bibliothek die Antwort überprüft hat, müssen Sie sicherstellen, dass die Anmeldedaten-ID für alle Nutzer eindeutig ist, bevor Sie die Anmeldedaten in Ihrer Datenbank speichern.
Eindeutigkeit der Anmeldedaten-ID prüfen
Fragen Sie Ihre Datenbank ab, um zu bestätigen, dass die zurückgegebene Anmeldedaten-ID (credential.id) noch nicht für einen Nutzer registriert ist, wie es die WebAuthn-Registrierungsschritte erfordern.
Zustandslose serverseitige FIDO-Bibliotheken haben keinen Zugriff auf Ihre Datenbank und können nicht nach doppelten Anmeldedaten-IDs suchen. Wenn die Anmeldedaten-ID bereits in Ihrer Datenbank vorhanden ist, lehnen Sie die Registrierungsanfrage sofort ab.
Anmeldedaten in Ihrer Datenbank speichern
Nachdem Sie die Registrierungsantwort überprüft und bestätigt haben, dass die Anmeldedaten-ID nicht verwendet wird, speichern Sie die Anmeldedaten in Ihrer Datenbank, damit sich der Nutzer später mit dem mit diesen Anmeldedaten verknüpften Passkey authentifizieren kann.
Verwenden Sie eine dedizierte Tabelle für die mit Passkeys verknüpften Anmeldedaten für öffentliche Schlüssel. Ein Nutzer kann nur ein Passwort, aber mehrere Passkeys haben – z. B. einen Passkey, der über den Apple iCloud-Schlüsselbund synchronisiert wird, und einen über den Google Passwortmanager.
Hier ist ein Beispielschema, das Sie zum Speichern von Anmeldedaten verwenden können:

- Tabelle Users:
user_id: Die primäre Nutzer-ID. Eine zufällige, eindeutige, permanente ID für den Nutzer. Verwenden Sie diese als Primärschlüssel für die Tabelle Users.username: Ein benutzerdefinierter Nutzername, der möglicherweise bearbeitet werden kann.passkey_user_id: Die Passkey-spezifische Nutzer-ID ohne personenidentifizierbare Informationen, die in Ihren Registrierungsoptionen durchuser.iddargestellt wird. Wenn der Nutzer später versucht, sich zu authentifizieren, stellt der Authenticator diesepasskey_user_idin seiner Authentifizierungsantwort inuserHandlezur Verfügung. Wir empfehlen,passkey_user_idnicht als Primärschlüssel festzulegen. Primärschlüssel werden in Systemen oft zu de facto personenidentifizierbaren Informationen, da sie häufig verwendet werden.
- Tabelle Anmeldedaten für öffentliche Schlüssel:
id: ID des Berechtigungsnachweises. Verwenden Sie diesen als einzigen Primärschlüssel (oder erzwingen Sie eine globaleUNIQUE-Einschränkung nur fürid) in Ihrer Tabelle Anmeldedaten für öffentliche Schlüssel. Verwenden Sie keinen zusammengesetzten Eindeutigkeitsschlüssel mitpasskey_user_id, der dieselbe Anmeldedaten-ID für mehrere Nutzerkonten zulassen würde. Konfigurieren Sie Einfügungen so, dass sie fehlschlagen, anstatt eine vorhandene Zeile bei einem Eindeutigkeitskonflikt zu überschreiben oder zu löschen.public_key: Öffentlicher Schlüssel der Anmeldedaten.passkey_user_id: Verwenden Sie dies als Fremdschlüssel, um eine Verknüpfung mit der Tabelle Users herzustellen.backed_up: Ein Passkey wird gesichert, wenn er vom Passkey-Anbieter synchronisiert wird. Das Speichern des Sicherungsstatus ist nützlich, wenn Sie in Zukunft Passwörter für Nutzer mitbacked_upPasskeys entfernen möchten. Sie können prüfen, ob der Passkey gesichert ist, indem Sie das BE-Flag inauthenticatorDatauntersuchen oder eine serverseitige FIDO-Bibliotheksfunktion verwenden, die normalerweise verfügbar ist, um Ihnen einfachen Zugriff auf diese Informationen zu ermöglichen. Das Speichern der Sicherungsberechtigung kann hilfreich sein, um potenzielle Nutzeranfragen zu beantworten.name: Optional ein Anzeigename für die Anmeldedaten, damit Nutzer den Anmeldedaten benutzerdefinierte Namen geben können.transports: Ein Array von Transporten. Das Speichern von Transporten ist für die Nutzerauthentifizierung nützlich. Wenn Übertragungsarten verfügbar sind, kann sich der Browser entsprechend verhalten und eine Benutzeroberfläche anzeigen, die der Übertragungsart entspricht, die der Passkey-Anbieter für die Kommunikation mit Clients verwendet. Das gilt insbesondere für Fälle der erneuten Authentifizierung, in denenallowCredentialsnicht leer ist.
Andere Informationen können für die Nutzerfreundlichkeit hilfreich sein, z. B. der Passkey-Anbieter, der Zeitpunkt der Erstellung der Anmeldedaten und der Zeitpunkt der letzten Verwendung. Weitere Informationen finden Sie unter Passkeys user interface design.
Beispielcode: Anmeldedaten speichern
In unseren Beispielen verwenden wir die SimpleWebAuthn-Bibliothek.
Hier übergeben wir die Überprüfung der Registrierungsantwort an die Funktion verifyRegistrationResponse.
import { isoBase64URL } from '@simplewebauthn/server/helpers';
router.post('/registerResponse', csrfCheck, sessionCheck, async (req, res) => {
const expectedChallenge = req.session.challenge;
const expectedOrigin = getOrigin(req.get('User-Agent'));
const expectedRPID = process.env.HOSTNAME;
const response = req.body;
// This sample code is for registering a passkey for an existing,
// signed-in user
// Ensure you nest verification function calls in try/catch blocks.
// If something fails, throw an error with a descriptive error message.
// Return that message with an appropriate error code to the client.
try {
// Verify the credential
const { verified, registrationInfo } = await verifyRegistrationResponse({
response,
expectedChallenge,
expectedOrigin,
expectedRPID,
requireUserVerification: false,
});
if (!verified) {
throw new Error('Verification failed.');
}
const {
aaguid,
credential,
credentialBackedUp
} = registrationInfo;
// Ensure the credential ID isn't already registered for any user.
// Stateless libraries like SimpleWebAuthn don't check your database for
// collisions.
const existingCredential = await Credentials.findById(credential.id);
if (existingCredential) {
throw new Error('Credential ID is already registered.');
}
// Name the credential based on AAGUID
const name =
aaguid === undefined ||
aaguid === '00000000-0000-0000-0000-000000000000' ?
req.useragent?.platform : aaguids[aaguid]?.name;
const base64PublicKey = isoBase64URL.fromBuffer(credential.publicKey);
// Existing, signed-in user
const { user } = res.locals;
// Insert the new credential. Use an insert-only operation (never an
// update or upsert) backed by a global unique constraint on `id` so
// concurrent duplicate requests fail instead of overwriting a credential.
await Credentials.create({
id: credential.id,
passkey_user_id: user.passkey_user_id,
publicKey: base64PublicKey,
name,
aaguid,
transports: credential.transports || response.response.transports,
backed_up: credentialBackedUp,
registered_at: new Date().getTime()
});
// Kill the challenge for this session
delete req.session.challenge;
return res.json(user);
} catch (e) {
delete req.session.challenge;
console.error(e);
return res.status(400).send({ error: e.message });
}
});
Anhang: AuthenticatorAttestationResponse
AuthenticatorAttestationResponse enthält zwei wichtige Objekte:
response.clientDataJSONist eine JSON-Version der Clientdaten, die im Web die Daten sind, die der Browser sieht. Sie enthält den RP-Ursprung, die Challenge undandroidPackageName, wenn der Client eine Android-App ist. Als RP können Sie durch das Lesen vonclientDataJSONauf Informationen zugreifen, die der Browser zum Zeitpunkt dercreate-Anfrage gesehen hat.response.attestationObjectenthält zwei Informationen:attestationStatement, was nur relevant ist, wenn Sie die Attestierung verwenden.authenticatorDatasind Daten, wie sie vom Passkey-Anbieter gesehen werden. Als vertrauende Partei erhalten Sie durch das Lesen vonauthenticatorDataZugriff auf die Daten, die der Passkey-Anbieter sieht und die zum Zeitpunkt dercreate-Anfrage zurückgegeben werden.
authenticatorData enthält wichtige Informationen zu den Anmeldedaten für den öffentlichen Schlüssel, die mit dem neu erstellten Passkey verknüpft sind:
- Die Public-Key-Anmeldedaten selbst und eine eindeutige Anmeldedaten-ID dafür.
- Die mit den Anmeldedaten verknüpfte RP-ID.
- Flags, die den Nutzerstatus beschreiben, als der Passkey erstellt wurde: ob ein Nutzer tatsächlich anwesend war und ob der Nutzer erfolgreich verifiziert wurde (siehe userVerification im Detail).
- Die AAGUID ist eine Kennung für den Passkey-Anbieter, z. B. den Google Passwortmanager. Anhand der AAGUID können Sie den Passkey-Anbieter identifizieren und den Namen auf einer Seite zur Passkey-Verwaltung anzeigen lassen. (siehe Passkey-Anbieter mit AAGUID ermitteln)
Obwohl authenticatorData in attestationObject verschachtelt ist, werden die darin enthaltenen Informationen für die Passkey-Implementierung benötigt, unabhängig davon, ob Sie die Attestierung verwenden oder nicht. authenticatorData ist codiert und enthält Felder, die in einem Binärformat codiert sind. Das Parsen und Decodieren wird in der Regel von Ihrer serverseitigen Bibliothek übernommen. Wenn Sie keine serverseitige Bibliothek verwenden, sollten Sie getAuthenticatorData() clientseitig nutzen, um sich serverseitige Parsing- und Decodierungsarbeiten zu ersparen.
Anhang: Überprüfung der Registrierungsantwort
Die Überprüfung der Registrierungsantwort umfasst die folgenden Prüfungen:
- Achten Sie darauf, dass die RP-ID mit Ihrer Website übereinstimmt.
- Prüfen Sie, ob der Ursprung der Anfrage ein erwarteter Ursprung für Ihre Website ist (URL der Hauptwebsite, Android-App).
- Wenn Sie eine Nutzerbestätigung benötigen, muss das Flag für die Nutzerbestätigung
authenticatorData.uvauftruegesetzt sein. - Das Flag für die Nutzeranwesenheit
authenticatorData.upwird normalerweise auftruegesetzt. Wenn die Anmeldedaten jedoch bedingt erstellt werden, wird es auffalsegesetzt. - Prüfen Sie, ob der Client die von Ihnen bereitgestellte Challenge bereitstellen konnte. Wenn Sie die Attestierung nicht verwenden, ist diese Prüfung nicht wichtig. Die Implementierung dieser Prüfung ist jedoch eine Best Practice: So ist Ihr Code bereit, falls Sie sich in Zukunft für die Verwendung der Attestierung entscheiden.
- Die Anmeldedaten-ID darf noch für keinen Nutzer registriert sein. Zustandslose serverseitige FIDO-Bibliotheken haben keinen Zugriff auf Ihre Datenbank. Sie müssen diese Prüfung also auf Ihrem Server implementieren und Duplikate ablehnen, anstatt vorhandene Anmeldedaten zu überschreiben, anzuhängen oder zu löschen. Weitere Informationen finden Sie unter Eindeutigkeit der Anmeldedaten-ID prüfen.
- Prüfen Sie, ob der Algorithmus, den der Passkey-Anbieter zum Erstellen der Anmeldedaten verwendet, einer der von Ihnen aufgeführten Algorithmen ist (in jedem
alg-Feld vonpublicKeyCredentialCreationOptions.pubKeyCredParams, das normalerweise in Ihrer serverseitigen Bibliothek definiert und für Sie nicht sichtbar ist). So wird sichergestellt, dass sich Nutzer nur mit Algorithmen registrieren können, die Sie zugelassen haben.
Weitere Informationen finden Sie im Quellcode von SimpleWebAuthn für verifyRegistrationResponse oder in der vollständigen Liste der Überprüfungen in der Spezifikation.