PublicKeyCredential: parseCreationOptionsFromJSON() statische Methode

Baseline 2025

Newly available

Since March 2025, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

Sicherer Kontext: Diese Funktion ist nur in sicheren Kontexten (HTTPS) in einigen oder allen unterstützenden Browsern verfügbar.

Die statische Methode parseCreationOptionsFromJSON() der PublicKeyCredential-Schnittstelle erstellt ein PublicKeyCredentialCreationOptions-Objekt aus einer JSON-Darstellung seiner Eigenschaften.

Die Methode ist eine praktische Funktion zum Konvertieren von Anmeldeinformationsoptionen, die von einem vertrauenden Server bereitgestellt werden, in eine Form, die eine Web-App verwenden kann, um Anmeldedaten zu erstellen.

Syntax

PublicKeyCredential.parseCreationOptionsFromJSON(options)

Parameter

options: Ein Objekt mit derselben Struktur wie ein PublicKeyCredentialCreationOptions, jedoch mit base64url-kodierten Zeichenketten anstelle von Puffer-Eigenschaften.

Rückgabewert

Ein PublicKeyCredentialCreationOptions-Objekt.

Ausnahmen

EncodingError DOMException: Wird ausgelöst, wenn das options-Objekt nicht in ein PublicKeyCredentialCreationOptions-Objekt konvertiert werden kann.
SecurityError DOMException: Die RP-Domäne ist nicht gültig.

Beschreibung

Der Web-Authentifizierungsprozess zum Erstellen eines Schlüsselpaares und Registrieren eines Benutzers beinhaltet, dass ein vertrauender Server der Web-App die Informationen bereitstellt, die zum Erstellen einer Anmeldeinformation erforderlich sind, einschließlich Informationen zur Benutzeridentität, der vertrauenden Partei und einer "Herausforderung". Die Web-App übergibt diese Informationen an einen Authentifikator, um die Anmeldeinformation zu erstellen, indem sie navigator.credentials.create() mit einem PublicKeyCredentialCreationOptions-Objekt als Argument aufruft.

Die Spezifikation definiert nicht, wie die Informationen zum Erstellen einer Anmeldeinformation gesendet werden. Ein praktischer Ansatz besteht darin, dass der Server die Informationen in einer JSON-Typdarstellung des PublicKeyCredentialCreationOptions-Objekts kapselt, das seine Struktur widerspiegelt, aber Puffer-Eigenschaften wie die challenge und user.id als base64url-Zeichenketten kodiert. Dieses Objekt kann in eine JSON-Zeichenkette serialisiert, an die Web-App gesendet und deserialisiert und dann mit parseCreationOptionsFromJSON() in ein PublicKeyCredentialCreationOptions-Objekt konvertiert werden.

Beispiele

Beim Registrieren eines neuen Benutzers liefert ein vertrauender Server der Web-App Informationen über die erwarteten Anmeldeinformationen. Der untenstehende Code definiert diese Informationen in der oben beschriebenen Form des options-Parameters (entnommen aus dem "Erhalt einer AuthenticatorAttestationResponse" in AuthenticatorResponse):

const createCredentialOptionsJSON = {
  challenge:
    "21, 31, 105, " /* 29 more random bytes generated by the server in this string */,
  rp: {
    name: "Example CORP",
    id: "login.example.com",
  },
  user: {
    id: "16",
    name: "[email protected]",
    displayName: "Carina Anand",
  },
  pubKeyCredParams: [
    {
      type: "public-key",
      alg: -7,
    },
  ],
};

Da dieses Objekt nur JSON-Datentypen verwendet, kann es mit JSON.stringify() in JSON serialisiert und an die Web-App gesendet werden.

JSON.stringify(createCredentialOptionsJSON);

Die Web-App kann die JSON-Zeichenkette zurück in ein createCredentialOptionsJSON-Objekt deserialisieren (nicht gezeigt). Die Methode parseCreationOptionsFromJSON() wird verwendet, um dieses Objekt in eine Form zu konvertieren, die in navigator.credentials.create() verwendet werden kann:

// Convert options to form used by create()
const createCredentialOptions =
  PublicKeyCredential.parseCreationOptionsFromJSON(
    createCredentialOptionsJSON, // JSON-type representation
  );

navigator.credentials
  .create({ publicKey: createCredentialOptions })
  .then((newCredentialInfo) => {
    // Handle the new credential information here.
  })
  .catch((err) => {
    console.error(err);
  });

Spezifikationen

Specification
Web Authentication: An API for accessing Public Key Credentials - Level 3 # dom-publickeycredential-parsecreationoptionsfromjson