PublicKeyCredential: parseRequestOptionsFromJSON() 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 parseRequestOptionsFromJSON() statische Methode des PublicKeyCredential-Interfaces wandelt eine JSON-Darstellungstyp in eine PublicKeyCredentialRequestOptions-Instanz um.

Diese Methode ist eine bequeme Funktion, um Informationen, die von einem verlassenden Server zur Verfügung gestellt werden, in einer Web-App zur Anforderung eines vorhandenen Berechtigungsnachweises zu konvertieren.

Syntax

PublicKeyCredential.parseRequestOptionsFromJSON(options)

Parameter

options: Ein Objekt mit derselben Struktur wie eine PublicKeyCredentialRequestOptions-Instanz, jedoch mit base64url-kodierten Zeichenfolgen anstelle von Buffer-Eigenschaften.

Rückgabewert

Eine PublicKeyCredentialRequestOptions-Instanz.

Ausnahmen

EncodingError DOMException: Wird ausgelöst, wenn ein Teil des options-Objekts nicht in eine PublicKeyCredentialRequestOptions-Instanz konvertiert werden kann.
SecurityError DOMException: Die RP-Domain ist nicht gültig.

Beschreibung

Der Web-Authentifizierungsprozess zur Authentifizierung eines (registrierten) Nutzers beinhaltet, dass ein vertrauender Server der Web-App die Informationen bereitstellt, die benötigt werden, um einen vorhandenen Berechtigungsnachweis zu finden, einschließlich Details über die Nutzeridentität, die vertrauende Partei, eine "Challenge" und optional, wo der Berechtigungsnachweis zu suchen ist: zum Beispiel auf einem lokalen integrierten Authenticator oder auf einem externen über USB, BLE usw. Die Web-App übermittelt diese Informationen an einen Authenticator, um den Berechtigungsnachweis zu finden, indem sie navigator.credentials.get() mit einem Argument aufruft, das die vom Server bereitgestellten Daten als PublicKeyCredentialRequestOptions-Instanz enthält.

Die Spezifikation definiert nicht, wie die Informationen, die für die Anforderung eines Berechtigungsnachweises benötigt werden, gesendet werden. Ein praktischer Ansatz besteht darin, dass der Server die Informationen in einer JSON-Darstellungstyp einer PublicKeyCredentialRequestOptions-Instanz kapselt, die seine Struktur widerspiegelt, aber Buffer-Eigenschaften wie die challenge als base64url-Zeichenfolgen kodiert. Dieses Objekt kann in eine JSON-Zeichenfolge serialisiert, an die Web-App gesendet, deserialisiert und dann mit parseRequestOptionsFromJSON() in eine PublicKeyCredentialRequestOptions-Instanz umgewandelt werden.

Beispiele

Bei der Autorisierung eines bereits registrierten Nutzers wird ein vertrauender Server der Web-App Informationen über die angeforderten Berechtigungsnachweise, die vertrauende Partei und eine Challenge bereitstellen. Der unten stehende Code definiert diese Informationen in der im options-Parameter beschriebenen Form:

const requestCredentialOptionsJSON = {
  challenge: new Uint8Array([139, 66, 181, 87, 7, 203 /* … */]),
  rpId: "acme.com",
  allowCredentials: [
    {
      type: "public-key",
      id: new Uint8Array([64, 66, 25, 78, 168, 226, 174 /* … */]),
    },
  ],
  userVerification: "required",
};

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

JSON.stringify(requestCredentialOptionsJSON);

Die Web-App kann die JSON-Zeichenfolge zurück in ein requestCredentialOptionsJSON-Objekt deserialisieren (nicht gezeigt). Die parseRequestOptionsFromJSON()-Methode wird verwendet, um dieses Objekt in die Form zu konvertieren, die in navigator.credentials.get() verwendet werden kann:

// Convert options to form used by get()
const publicKey = PublicKeyCredential.parseRequestOptionsFromJSON(
  requestCredentialOptionsJSON, // JSON-type representation
);

navigator.credentials
  .get({ publicKey })
  .then((returnedCredentialInfo) => {
    // Handle the returned credential information here.
  })
  .catch((err) => {
    console.error(err);
  });

Spezifikationen

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