Signatur
Beschreibung
Die statische Methode PublicKeyCredential.parseCreationOptionsFromJSON() nimmt die JSON-Darstellung von Registrierungsoptionen entgegen, wie sie ein WebAuthn-Server typischerweise liefert, und erzeugt daraus ein PublicKeyCredentialCreationOptions-Objekt. Dieses Objekt kann direkt als publicKey-Option an navigator.credentials.create() übergeben werden, um einen neuen Passkey bzw. ein neues Public-Key-Credential zu registrieren.
Das Problem, das die Methode löst: Binärfelder wie challenge, user.id und excludeCredentials[].id müssen für die WebAuthn-API als ArrayBuffer vorliegen, JSON kann aber nur Zeichenketten transportieren. Server kodieren diese Werte daher als Base64URL. Früher musste man die Dekodierung selbst schreiben oder Bibliotheken wie @github/webauthn-json einsetzen; parseCreationOptionsFromJSON() erledigt das jetzt nativ und gemäß Spezifikation.
Das Gegenstück für den Rückweg ist PublicKeyCredential.prototype.toJSON(), das das erzeugte Credential wieder in eine JSON-taugliche Form (Base64URL) umwandelt, damit es an den Server geschickt werden kann. Für den Anmeldevorgang gibt es analog PublicKeyCredential.parseRequestOptionsFromJSON().
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $options Pflicht | PublicKeyCredentialCreationOptionsJSON (Object) | Objekt mit derselben Struktur wie PublicKeyCredentialCreationOptions, jedoch mit Base64URL-kodierten Strings statt ArrayBuffer für challenge, user.id, excludeCredentials[].id sowie ggf. Binärwerte in Erweiterungen. Pflicht sind u. a. rp, user (id, name, displayName), challenge und pubKeyCredParams. |
Rückgabewert
ArrayBuffer dekodiert wurden – bereit für navigator.credentials.create({ publicKey }).Beispiele
Passkey-Registrierung mit Serveroptionen
const registerPasskey = async () => {
// Optionen als JSON vom Server holen
const res = await fetch('/webauthn/register/options', { method: 'POST' });
const optionsJSON = await res.json();
// Base64URL-Felder in ArrayBuffer umwandeln
const publicKey = PublicKeyCredential.parseCreationOptionsFromJSON(optionsJSON);
const credential = await navigator.credentials.create({ publicKey });
// Ergebnis wieder als JSON zum Server schicken
await fetch('/webauthn/register/verify', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(credential.toJSON())
});
console.log('Passkey registriert:', credential.id);
};
registerPasskey().catch(console.error);Aufbau des JSON-Objekts und Prüfung des Ergebnisses
const optionsJSON = {
rp: { id: 'example.com', name: 'Beispiel GmbH' },
user: {
id: 'dXNlci0xMjM0', // Base64URL von "user-1234"
name: 'anna@example.com',
displayName: 'Anna Beispiel'
},
challenge: 'Y2hhbGxlbmdlLTk4NzY1NDMyMQ',
pubKeyCredParams: [
{ type: 'public-key', alg: -7 }, // ES256
{ type: 'public-key', alg: -257 } // RS256
],
timeout: 60000,
excludeCredentials: [],
authenticatorSelection: { residentKey: 'required', userVerification: 'preferred' },
attestation: 'none'
};
const options = PublicKeyCredential.parseCreationOptionsFromJSON(optionsJSON);
console.log(options.challenge instanceof ArrayBuffer);
console.log(new TextDecoder().decode(options.user.id));Feature-Erkennung mit Fallback
const base64urlToBuffer = (str) => {
const b64 = str.replace(/-/g, '+').replace(/_/g, '/');
const padded = b64 + '='.repeat((4 - (b64.length % 4)) % 4);
return Uint8Array.from(atob(padded), (c) => c.charCodeAt(0)).buffer;
};
const toCreationOptions = (json) => {
if (typeof PublicKeyCredential?.parseCreationOptionsFromJSON === 'function') {
return PublicKeyCredential.parseCreationOptionsFromJSON(json);
}
// Manueller Fallback für ältere Browser
return {
...json,
challenge: base64urlToBuffer(json.challenge),
user: { ...json.user, id: base64urlToBuffer(json.user.id) },
excludeCredentials: (json.excludeCredentials ?? []).map((c) => ({
...c,
id: base64urlToBuffer(c.id)
}))
};
};
console.log(typeof toCreationOptions);// Wichtig · Fallstricke
- Browser-Kompatibilität: Relativ neue Methode (WebAuthn Level 3). Unterstützt ab Chrome/Edge 129, Firefox 119 und Safari 18.4. Vor der Nutzung per
typeof PublicKeyCredential.parseCreationOptionsFromJSON === 'function'prüfen und ggf. einen Fallback bereitstellen. - Fehler: Enthält das Objekt ungültiges Base64URL (z. B. Standard-Base64 mit
+,/oder=-Padding bei manchen Implementierungen) oder fehlen Pflichtfelder, wirft die Methode einenEncodingError(DOMException) bzw.TypeError. - Keine Sicherheitsprüfung: Die Methode wandelt nur Datenformate um. Die
challengemuss serverseitig zufällig erzeugt und bei der Verifizierung geprüft werden; auch Attestierung und Origin-Prüfung erfolgen ausschließlich auf dem Server. - WebAuthn funktioniert nur in einem sicheren Kontext (HTTPS oder
localhost);rp.idmuss zur aktuellen Domain passen. - Nicht mit
parseRequestOptionsFromJSON()verwechseln – diese ist für die Anmeldung (navigator.credentials.get()) gedacht.