DasPublicKeyCredentialCreationOptions Wörterbuch repräsentiert das Objekt, das anCredentialsContainer.create() als Wert der OptionpublicKey übergeben wird: also, wenncreate() verwendet wird, um ein öffentliches Schlüssel-Anmeldedaten mit derWeb Authentication API zu erstellen.

Instanzeigenschaften

attestationOptional

Ein String, der die Präferenz der vorhergehenden Instanz (relying party) angibt, wie die Attestierungserklärung (d.h. die Bereitstellung nachweisbarer Beweise für die Authentizität des Authentifizierers und seiner Daten) während der Erstellung der Anmeldedaten übermittelt wird. Der Wert kann einer der folgenden sein:

"none"

Gibt an, dass die vorhergehende Instanz nicht an Authentifikator-Attestierung interessiert ist. Dies könnte dazu dienen, zusätzliche Benutzerzustimmungen für Rückreisen zum Server der vorhergehenden Instanz zu vermeiden, um identifizierende Informationen weiterzuleiten, oder Rückreisen zu einer Attestierungszertifizierungsstelle (CA), mit dem Ziel, den Authentifizierungsprozess reibungsloser zu gestalten. Wenn"none" alsattestation-Wert gewählt wird und der Authentifikator signalisiert, dass er eine CA verwendet, um seine Attestierungserklärung zu generieren, ersetzt die Client-App diese mit einer "None" Attestierungserklärung, was anzeigt, dass keine Attestierungserklärung verfügbar ist.

"direct"

Gibt an, dass die vorhergehende Instanz die Attestierungserklärung erhalten möchte, wie sie vom Authentifikator generiert wurde.

"enterprise"

Gibt an, dass die vorhergehende Instanz eine Attestierungserklärung erhalten möchte, die möglicherweise eindeutig identifizierende Informationen enthält. Dies ist für kontrollierte Bereitstellungen innerhalb eines Unternehmens gedacht, wo die Organisation Registrierungen an bestimmte Authentifikatoren binden möchte.

"indirect"

Gibt an, dass die vorhergehende Instanz eine verifizierbare Attestierungserklärung erhalten möchte, dem Client jedoch erlaubt, zu entscheiden, wie er sie erhält. Der Client könnte beispielsweise wählen, die Assertionserklärung des Authentifikators durch eine von einer Anonymisierungs-CA generierte zu ersetzen, um die Privatsphäre des Benutzers zu schützen.

Wennattestation weggelassen wird, wird es standardmäßig auf"none" gesetzt.

attestationFormatsOptional

Ein Array von Strings, das die Präferenz der vorhergehenden Instanz für das von Authentifikator verwendete Attestierungsformat angibt. Werte sollten von höchster zu niedrigster Präferenz geordnet sein und sollten als Hinweise betrachtet werden — der Authentifikator kann wählen, eine Attestierungserklärung in einem anderen Format auszustellen. Eine Liste gültiger Formate finden Sie unterWebAuthn Attestation Statement Format Identifiers.

Wenn weggelassen, istattestationFormats standardmäßig ein leeres Array.

authenticatorSelectionOptional

Ein Objekt, dessen Eigenschaften Kriterien sind, um die potenziellen Authentifikatoren für den Anmeldedatenerstellungsvorgang herauszufiltern. Dieses Objekt kann die folgenden Eigenschaften enthalten:

authenticatorAttachmentOptional

Ein String, der angibt, welcher Typ von Authentifikator-Anhang für den gewählten Authentifikator zulässig sein soll. Mögliche Werte sind:

"platform"

Der Authentifikator ist Teil des Geräts, auf dem WebAuthn läuft (alsPlattformauthentifikator bezeichnet), und daher wird WebAuthn mit ihm über ein auf dieser Plattform verfügbares Transportmittel kommunizieren, wie eine plattformspezifische API. Ein öffentliches Schlüssel-Anmeldedaten gebunden an einen Plattformauthentifikator wird alsPlattform-Anmeldedaten bezeichnet.

"cross-platform"

Der Authentifikator ist nicht Teil des Geräts, auf dem WebAuthn läuft (alsbeweglicher Authentifikator bezeichnet, da er zwischen verschiedenen Geräten wechseln kann), und daher wird WebAuthn mit ihm über ein plattformübergreifendes Transportprotokoll wie Bluetooth oder NFC kommunizieren. Ein öffentliches Schlüssel-Anmeldedaten gebunden an einen beweglichen Authentifikator wird alsbewegliche Anmeldedaten bezeichnet.

Wenn weggelassen, kann für den Anmeldedatenerstellungsvorgang jeder Typ von Authentifikator, entweder Plattform oder plattformübergreifend, ausgewählt werden.

requireResidentKeyOptional

Ein Boolean. Wenn auftrue gesetzt, zeigt es an, dass die vorhergehende Instanz einermittelbares Anmeldedatum erstellen möchte.

Diese Option wird nur aus Gründen der Abwärtskompatibilität beibehalten: Anrufer sollten stattdessen dieresidentKey Option verwenden. WennresidentKey angegeben ist und unterstützt wird, wirdrequireResidentKey ignoriert. DierequireResidentKey Option sollte nur dann auftrue gesetzt werden, wennresidentKey auf"required" gesetzt ist.

Standard istfalse.

residentKeyOptional

Ein String, der angibt, in welchem Umfang die vorhergehende Instanz einermittelbares Anmeldedatum erstellen möchte.Mögliche Werte sind:

"discouraged"

Die vorhergehende Instanz zieht die Erstellung eines serverseitigen Anmeldedatums vor, akzeptiert jedoch auch ein clientseitig ermittelbares Anmeldedatum.

"preferred"

Die vorhergehende Instanz zieht es dringend vor, ein ermittelbares Anmeldedatum zu erstellen, akzeptiert jedoch auch ein nicht ermittelbares Anmeldedatum. Der Benutzeragent sollte den Benutzer durch die Einrichtung der Benutzerverifizierung führen, falls erforderlich, um ein ermittelbares Anmeldedatum zu erstellen. Dies hat Vorrang vor deruserVerification Einstellung.

"required"

Die vorhergehende Instanz erfordert ein ermittelbares Anmeldedatum. Wenn eines nicht erstellt werden kann, wird einNotAllowedErrorDOMException ausgelöst. Siehe diecreate() Ausnahmeliste für weitere Details.

Wenn weggelassen, istresidentKey standardmäßig auf"required" gesetzt, wennrequireResidentKeytrue ist, andernfalls ist der Standardwert"discouraged".

userVerificationOptional

Ein String, der die Anforderungen der vorhergehenden Instanz für die Benutzerverifizierung für dencreate()-Vorgang angibt. Mögliche Werte sind:

"discouraged"

Die vorhergehende Instanz zieht keine Benutzerverifizierung für dencreate()-Vorgang vor, um die Benutzererfahrung so wenig wie möglich zu stören.

"preferred"

Die vorhergehende Instanz bevorzugt Benutzerverifizierung für dencreate()-Vorgang, schlägt jedoch nicht fehl, wenn die Benutzerverifizierung nicht durchgeführt werden kann.

"required"

Die vorhergehende Instanz erfordert Benutzerverifizierung für dencreate()-Vorgang — wenn die Benutzerverifizierung nicht durchgeführt werden kann, wird ein Fehler ausgelöst.

Wenn weggelassen, istuserVerification standardmäßig auf"preferred" gesetzt.

challenge

EinArrayBuffer,TypedArray, oderDataView, bereitgestellt vom Server der vorhergehenden Instanz und verwendet alskryptografische Herausforderung. Dieser Wert wird vom Authentifikator signiert und die Signatur wird als Teil desAuthenticatorAttestationResponse.attestationObject zurückgesandt.

excludeCredentialsOptional

EinArray von Objekten, die vorhandene Anmeldedaten beschreiben, die bereits diesem Benutzerkonto (wie durchuser.id identifiziert) zugeordnet sind. Dies wird von der vorhergehenden Instanz bereitgestellt und vom Benutzeragent überprüft, um die Erstellung eines neuen öffentlichen Schlüssel-Anmeldedatums auf einem Authentifikator zu vermeiden, der bereits eine Anmeldedaten mit dem angegebenen Benutzerkonto zugeordnet hat. Jedes Element sollte die folgende Form haben:

id

EinArrayBuffer,TypedArray, oderDataView repräsentiert die ID des vorhandenen Anmeldedaten.

transportsOptional

EinArray von Strings, die erlaubte Transporte repräsentieren. Mögliche Transporte sind:"ble","hybrid","internal","nfc", und"usb" (siehegetTransports() für weitere Details).

type

Ein String, der den Typ der zu erstellenden öffentlichen Schlüssel-Anmeldedaten definiert. Dies kann derzeit einen einzigen Wert aufnehmen,"public-key", aber in Zukunft könnten mehr Werte hinzugefügt werden.

Wenn dercreate()-Aufruf versucht, ein doppeltes öffentliches Schlüssel-Anmeldedatum auf einem Authentifikator zu erstellen, wird der Benutzeragent den Benutzer anleiten, das Anmeldedatum mit einem anderen Authentifikator zu erstellen oder zu scheitern, wenn das nicht möglich ist.

WennexcludeCredentials weggelassen wird, ist es standardmäßig ein leeres Array.

extensionsOptional

Ein Objekt, das Eigenschaften enthält, die die Eingabewerte für alle angeforderten Erweiterungen darstellen. Diese Erweiterungen werden verwendet, um zusätzliche Verarbeitungen durch den Client oder Authentifikator während des Anmeldedatenerstellungsvorgangs zu spezifizieren. Beispiele umfassen die Angabe, ob ein zurückgegebenes Anmeldedatum ermittelbar ist oder ob die vorhergehende Instanz große Blobdaten speichern können soll, die einem Anmeldedatum zugeordnet sind.

Erweiterungen sind optional und verschiedene Browser können verschiedene Erweiterungen erkennen. Die Verarbeitung von Erweiterungen ist für den Client immer optional: Wenn ein Browser eine bestimmte Erweiterung nicht erkennt, ignoriert er sie einfach. Informationen zur Verwendung von Erweiterungen und welche von welchen Browsern unterstützt werden, finden Sie unterWeb Authentication extensions.

hintsOptionalExperimentell

Ein Array von Strings, das Hinweise darauf gibt, welche Benutzeroberfläche der Browser bieten sollte, um ein öffentliches Schlüssel Anmeldedatum zu erstellen.

Die Strings können einer der folgenden sein:

"security-key"

Die Benutzeroberfläche sollte empfehlen, einen separaten physischen Sicherheitsschlüssel (wie einen YubiKey) zu verwenden, um das Anmeldedatum zu erstellen.

"client-device"

Die Benutzeroberfläche sollte empfehlen, einen Authentifikator zu verwenden, der auf dem gleichen Gerät verfügbar ist, das sie verwenden, um auf den RP-Client zuzugreifen, um das Anmeldedatum zu erstellen. Es ist analog zumauthenticatorAttachmentplatform Wert.

"hybrid"

Die Benutzeroberfläche sollte empfehlen, einen allgemeinen Authentifikator, wie eine Smartphone-basierte Authentifikator-App, zu verwenden, um das Anmeldedatum zu erstellen. Dies bevorzugt einen geräteübergreifenden Ansatz zur Handhabung von Authentifizierung und setzt auf eine Kombination aus Laptop und Smartphone, zum Beispiel.

DerauthenticatorAttachmentcross-platform Wert ist im Wesentlichen eine Kombination aus denhints Optionensecurity-key undhybrid Werten — wenn ein Gerät kein Bluetooth hat und ein RPattachment: "cross-platform" angibt, wird die resultierende Benutzeroberfläche wahrscheinlich ähnlich derhints: "security-key" Benutzeroberfläche sein.

Wenn mehrere Strings im Array enthalten sind, gibt ihre Reihenfolge die Präferenzreihenfolge von hoch zu niedrig an. Unterstützende Browser, die die Hinweise respektieren, sollten den ersten verwenden, den sie verstehen.

Diehints Option bietet eine flexiblere Möglichkeit, Benutzeroberflächenpräferenzen für die Erstellung eines Anmeldedatums anzugeben als dieauthenticatorAttachment Option, die die nicht gewählte Option vollständig verbirgt.hints ermöglichen es auch, eine Präferenz für entweder Sicherheitsschlüssel oder Hybrid anzugeben, was mitauthenticatorAttachment nicht möglich ist.

Angegebenehints können im Widerspruch zu Hinweisen stehen, die in derauthenticatorAttachment Option bereitgestellt wurden. Wenn die angegebenenhints dieser Option widersprechen, haben diehints Vorrang.hints können auch vom Browser unter bestimmten Umständen ignoriert werden, zum Beispiel wenn ein angedeuteter Authentifikatortyp auf dem Gerät des Benutzers nicht verwendbar ist.

Für einige spezifische Code- und UI-Beispiele sieheIntroducing hints, Related Origin Requests and JSON serialization for WebAuthn in Chrome.

pubKeyCredParams

EinArray von Objekten, die die Schlüsseltpyen und Signaturalgorithmen spezifizieren, die die vorhergehende Instanz unterstützt, geordnet von der bevorzugtesten bis zur am wenigsten bevorzugten. Der Client und der Authentifikator werden sich bemühen, ein Anmeldedatum des am meisten bevorzugten Typs zu erstellen. Diese Objekte enthalten die folgenden Eigenschaften:

alg

Eine Zahl, die einemCOSE-Algorithmus-Identifikator entspricht und den kryptografischen Algorithmus darstellt, der für diesen Anmeldedatentyp verwendet werden soll. Es wird empfohlen, dass vorhergehende Instanzen, die eine breite Palette von Authentifikatoren unterstützen möchten, mindestens die folgenden Werte in den bereitgestellten Optionen einschließen:

• -8: EdDSA
• -7: ES256
• -257: RS256

type

Ein String, der den Typ der zu erstellenden öffentlichen Schlüssel-Anmeldedaten definiert. Dies kann derzeit einen einzigen Wert aufnehmen,"public-key", aber in Zukunft könnten mehr Werte hinzugefügt werden.

Wenn keiner der angegebenen Anmeldedatentypen erstellt werden kann, schlägt dercreate()-Vorgang fehl.

rp

Ein Objekt, das die vorhergehende Instanz beschreibt, die die Erstellung der Anmeldedaten angefordert hat. Es kann die folgenden Eigenschaften enthalten:

idOptional

Ein String, der die ID der vorhergehenden Instanz repräsentiert. Ein öffentliches Schlüssel-Anmeldedaten kann nur zur Authentifizierung mit der gleichen vorhergehenden Instanz verwendet werden (wie durch diepublicKey.rpId in einemnavigator.credentials.get()-Aufruf identifiziert), mit der es registriert wurde — die IDs müssen übereinstimmen.

Dieid kann keinen Port oder Schema wie ein standardmäßiger Ursprung einschließen, aber das Domainschema musshttps sein. Dieid muss der effektiven Domäne des Ursprungs entsprechen oder ein Domain-Suffix davon sein. Zum Beispiel, wenn der Ursprung der vorhergehenden Instanzhttps://login.example.com:1337 ist, sind die folgendenids gültig:

• login.example.com
• example.com

Aber nicht:

• m.login.example.com
• com

Wenn weggelassen, wirdid standardmäßig auf den Dokumenten-Ursprung gesetzt — was in diesem Beispiellogin.example.com wäre.

name

Ein String, der den Namen der vorhergehenden Instanz repräsentiert (z.B."Facebook"). Dies ist der Name, der dem Benutzer angezeigt wird, wenn er eine WebAuthn-Operation erstellt oder validiert.

timeoutOptional

Ein numerischer Hinweis in Millisekunden, der angibt, wie lange die aufrufende Web-App bereit ist, auf den Abschluss des Erstellvorgangs zu warten. Dieser Hinweis kann vom Browser überschrieben werden.

user

Ein Objekt, das das Benutzerkonto beschreibt, für welches das Anmeldedatum generiert wird. Es kann die folgenden Eigenschaften enthalten:

displayName

Ein String, der einen benutzerfreundlichen Anzeigemamen (Beispiel:"Maria Sanchez") bereitstellt, den der Benutzer während der anfänglichen Registrierung bei der vorhergehenden Instanz festgelegt haben wird.

id

EinArrayBuffer,TypedArray, oderDataView repräsentiert eine eindeutige ID für das Benutzerkonto. Dieser Wert hat eine maximale Länge von 64 Bytes und ist nicht für die Anzeige für den Benutzer vorgesehen.

name

Ein String, der eine benutzerfreundliche Kennung für das Benutzerkonto des Benutzers bereitstellt, um dabei zu helfen, zwischen verschiedenen Konten mit ähnlichendisplayNames zu unterscheiden. Dies könnte eine E-Mail-Adresse (z.B."elaina.sanchez@example.com"), Telefonnummer (z.B."+12345678901"), oder eine andere Art von Benutzerkonto-Kennung (z.B."ElainaSanchez667") sein.

Beispiele

Erstellen eines öffentlichen Schlüssel-Anmeldedatums

Dieses Beispiel erstellt einPublicKeyCredentialCreationOptions, indem nur die erforderlichen Eigenschaften angegeben und die Standards für den Rest verwendet werden.

Dann wird das Objekt innavigator.credentials.create() übergeben, um ein neues öffentliches Schlüssel-Anmeldedatum zu erstellen.

const publicKey = {  challenge: challengeFromServer,  rp: { id: "acme.com", name: "ACME Corporation" },  user: {    id: new Uint8Array([79, 252, 83, 72, 214, 7, 89, 26]),    name: "jamiedoe",    displayName: "Jamie Doe",  },  pubKeyCredParams: [{ type: "public-key", alg: -7 }],};const publicKeyCredential = await navigator.credentials.create({ publicKey });

Ein erfolgreichercreate()-Aufruf gibt ein Versprechen zurück, das mit einerPublicKeyCredential-Objektinstanz auflöst, die ein öffentliches Schlüssel-Anmeldedatum repräsentiert, das später verwendet werden kann, um einen Benutzer über einen WebAuthnget()-Aufruf zu authentifizieren. SeinePublicKeyCredential.response-Eigenschaft enthält einAuthenticatorAttestationResponse-Objekt, das Zugriff auf mehrere nützliche Informationen bietet, einschließlich der Authentifikatordaten, öffentlicher Schlüssel, Transportmechanismen und mehr.

navigator.credentials.create({ publicKey }).then((publicKeyCredential) => {  const response = publicKeyCredential.response;  // Access attestationObject ArrayBuffer  const attestationObj = response.attestationObject;  // Access client JSON  const clientJSON = response.clientDataJSON;  // Return authenticator data ArrayBuffer  const authenticatorData = response.getAuthenticatorData();  // Return public key ArrayBuffer  const pk = response.getPublicKey();  // Return public key algorithm identifier  const pkAlgo = response.getPublicKeyAlgorithm();  // Return permissible transports array  const transports = response.getTransports();});

Einige dieser Daten müssen auf dem Server für zukünftige Authentifizierungsvorgänge gegen dieses Anmeldedatum gespeichert werden — zum Beispiel der öffentliche Schlüssel, der verwendete Algorithmus und die zulässigen Transporte.

SieheErstellen eines Schlüsselpaares und Registrieren eines Benutzers für weitere Informationen darüber, wie der gesamte Ablauf funktioniert.

Spezifikationen

Browser-Kompatibilität