Get to know MDN better
Dieser Inhalt wurde automatisch aus dem Englischen übersetzt, und kann Fehler enthalten. Erfahre mehr über dieses Experiment.
Diese Funktion ist gut etabliert und funktioniert auf vielen Geräten und in vielen Browserversionen. Sie ist seit September 2019 browserübergreifend verfügbar.
* Einige Teile dieser Funktion werden möglicherweise unterschiedlich gut unterstützt.
Die Web Authentication API verfügt über ein System von Erweiterungen – zusätzliche Funktionen, die während der Erstellung von Anmeldeinformationen (navigator.credentials.create()) oder Authentifizierungsoperationen (navigator.credentials.get()) angefordert werden können. Dieser Artikel erklärt, wie Sie WebAuthn-Erweiterungen anfordern, Informationen über die Antworten auf diese Anfragen abrufen und welche Erweiterungen verfügbar sind – einschließlich Browser-Unterstützung sowie erwarteter Eingaben und Ausgaben.
Beim Aufruf von navigator.credentials.create() oder navigator.credentials.get() kann das erforderliche publicKey-Objekt, um einen WebAuthn-Flow zu initiieren, eine extensions-Eigenschaft enthalten. Der Wert von extensions ist selbst ein Objekt, dessen Eigenschaften die Eingabewerte für alle Erweiterungen sind, die die vertrauende Seite in der von Ihnen aufgerufenen Methode nutzen möchte.
Hinter den Kulissen werden die Eingaben vom Benutzeragenten und/oder dem Authentifikator verarbeitet.
Zum Beispiel könnten wir in einem publicKey-Objekt für einen create()-Aufruf die Nutzung von zwei Erweiterungen anfordern:
Wir können dann das publicKey-Objekt in einen create()-Aufruf übergeben, um den Flow zur Erstellung von Anmeldeinformationen zu initiieren:
Wenn erfolgreich, gibt der create()-Aufruf ein Promise zurück, das sich mit einem PublicKeyCredential-Objekt auflöst. Sobald die Verarbeitung der Erweiterungen abgeschlossen ist, werden die Ergebnisse dieser Verarbeitung in der Antwort kommuniziert (obwohl nicht in allen Fällen – es ist möglich, dass Erweiterungen keine Ausgabe haben).
Wie das obige Code-Snippet zeigt, gibt es zwei verschiedene Orte, an denen Sie Ihre output-Erweiterungsergebnisse finden können:
Sie können die Ergebnisse der Client (Benutzeragenten) Erweiterungsverarbeitung finden, indem Sie die Methode PublicKeyCredential.getClientExtensionResults() aufrufen. Diese gibt eine map zurück, wobei jeder Eintrag ein Erweiterungs-Identifikator-String als Schlüssel und die Ausgabe aus der Verarbeitung der Erweiterung durch den Client als Wert enthält. In dem obigen Beispiel würde, wenn der Browser die credProps-Erweiterung unterstützt und korrekt verarbeitet wurde, das myClientExtResults-Map-Objekt einen Eintrag, "credProps", mit einem Wert von { rk: true } enthalten. Dies würde bestätigen, dass die erstellte Anmeldeinformation tatsächlich erkennbar ist.
Sie können die Ergebnisse der Authentifikator-Erweiterungsverarbeitung in den Authentifikatordaten für die Operation finden:
Authentifikatordaten nehmen die Form eines ArrayBuffer mit einer konsistenten Struktur an – siehe authenticator data. Die Daten der Ergebnisse von Authentifikator-Erweiterungen sind immer in einem Abschnitt am Ende zu finden, als CBOR-Karte, die die Ergebnisse darstellt. Siehe AuthenticatorAssertionResponse.authenticatorData für eine detaillierte Beschreibung der vollständigen Struktur der Authentifikatordaten.
Zurück zu unserem Beispiel, wenn die vertrauende Partei autorisiert ist, den minPinLength-Wert zu erhalten, würden die Authentifikatordaten eine Darstellung dessen in folgender Form enthalten: "minPinLength": uint.
Die unten aufgeführten Erweiterungen stellen keine vollständige Liste aller verfügbaren Erweiterungen dar. Wir haben uns entschieden, Erweiterungen zu dokumentieren, die nachweislich standardisiert und von mindestens einem Rendering-Engine unterstützt werden.
Ermöglicht es einer vertrauenden Partei, eine Behauptung für ein zuvor mit der Legacy-FIDO U2F JavaScript-API registriertes Credential anzufordern, um die Mühe der erneuten Registrierung der Anmeldeinformationen zu vermeiden. Das appid ist das Äquivalent von WebAuthn's rpId (obwohl zu beachten ist, dass appids in Form von URLs vorliegen, während rpIds in Form von Domains vorliegen).
Die extensions-Eigenschaft des publicKey muss eine appid-Eigenschaft enthalten, deren Wert der in der Legacy-API verwendete Anwendungkennzeichner ist. Zum Beispiel:
Sie müssen auch die FIDO U2F-Anmeldeinformationen-IDs in der allowCredentials-Eigenschaft des publicKey auflisten, zum Beispiel:
Gibt appid: true aus, wenn das appid erfolgreich für die Behauptung verwendet wurde, oder appid: false andernfalls.
Ermöglicht es einer vertrauenden Partei, Authentikatoren mit bestimmten Anmeldeinformationen auszuschließen, die zuvor mit der Legacy-FIDO U2F JavaScript-API während der Registrierung registriert wurden. Dies ist erforderlich, da standardmäßig der Inhalt des Feldes excludeCredentials als WebAuthn-Anmeldeinformationen angenommen wird. Wenn Sie diese Erweiterung verwenden, können Sie Legacy-FIDO U2F-Anmeldeinformationen in excludeCredentials aufnehmen, und sie werden als solche erkannt.
Die extensions-Eigenschaft des publicKey muss eine appidExclude-Eigenschaft enthalten, deren Wert der Kennzeichner der vertrauenden Partei ist, die Authentikatoren anhand von Legacy-FIDO U2F-Anmeldeinformationen ausschließen möchte. Zum Beispiel:
Sie können dann FIDO U2F-Anmeldeinformationen in der excludeCredentials-Eigenschaft des publicKey auflisten, zum Beispiel:
Gibt appidExclude: true aus, wenn die Erweiterung beachtet wurde, oder appidExclude: false andernfalls.
Ermöglicht es einer vertrauenden Partei, zusätzliche Informationen/Eigenschaften über das erstellte Credential zu erhalten. Dies ist derzeit nur nützlich, wenn create() mit publicKey.authenticatorSelection.residentKey = "preferred" aufgerufen wird; es fordert Informationen darüber an, ob das erstellte Credential erkennbar ist.
Die extensions-Eigenschaft des publicKey muss eine credProps-Eigenschaft mit einem Wert von true enthalten:
Sie müssen auch authenticatorSelection.requireResidentKey auf true setzen, was angibt, dass ein ansässiger Schlüssel erforderlich ist.
Gibt das Folgende aus, wenn das registrierte PublicKeyCredential ein clientseitig erkennbares Credential ist:
Wenn rk im Output auf false gesetzt ist, ist das Credential ein serverseitiges Credential. Wenn rk im Output nicht vorhanden ist, ist es unbekannt, ob das Credential clientseitig erkennbar oder serverseitig ist.
Ermöglicht es einer vertrauenden Partei, eine Mindest-Credential-Schutzrichtlinie festzulegen, wenn ein Credential erstellt wird.
Die extensions-Eigenschaft des publicKey muss eine credentialProtectionPolicy-Eigenschaft enthalten, die das Schutzlevel des zu erstellenden Credentials angibt, und eine boolesche Eigenschaft enforceCredentialProtectionPolicy, die angibt, ob der create()-Aufruf fehlschlagen soll, anstatt ein Credential zu erstellen, das nicht den angegebenen Richtlinien entspricht:
Die verfügbaren credentialProtectionPolicy-Werte sind wie folgt:
"userVerificationOptional"Benutzerüberprüfung ist optional. Der entsprechende credProtect-Wert, der an den Authentifikator zur Verarbeitung gesendet wird, ist 0x01.
"userVerificationOptionalWithCredentialIDList"Benutzerüberprüfung ist nur dann optional, wenn das Credential erkennbar ist (d.h. es ist clientseitig erkennbar). Der entsprechende credProtect-Wert, der an den Authentifikator zur Verarbeitung gesendet wird, ist 0x02.
"userVerificationRequired"Benutzerüberprüfung ist immer erforderlich. Der entsprechende credProtect-Wert, der an den Authentifikator zur Verarbeitung gesendet wird, ist 0x03.
Hinweis: Chromium wird standardmäßig auf userVerificationOptionalWithCredentialIDList oder userVerificationRequired setzen, abhängig von der Art der Anfrage:
Angenommen, der Wert enforceCredentialProtectionPolicy ist true. In diesem Fall wird der create()-Aufruf fehlschlagen, wenn die Richtlinie nicht eingehalten werden kann (zum Beispiel wird Benutzerüberprüfung gefordert, aber der Authentifikator unterstützt keine Benutzerüberprüfung). Ist er false, versucht das System, ein Credential zu erstellen, das der Richtlinie so gut wie möglich entspricht, wird jedoch trotzdem eines erstellen, das so nah wie möglich konform ist, wenn dies nicht möglich ist.
Wenn der create()-Aufruf erfolgreich ist, enthalten die Authentifikatordaten eine Darstellung des credProtect-Werts, der die festgelegte Richtlinie in folgender Form repräsentiert:
Ermöglicht es einer vertrauenden Partei, Blobs, die mit einem Credential auf dem Authentifikator assoziiert sind, zu speichern – zum Beispiel könnte sie Zertifikate direkt speichern wollen, anstatt einen zentralisierten Authentifizierungsdienst zu betreiben.
Während eines create()-Aufrufs muss die extensions-Eigenschaft des publicKey eine largeBlob-Eigenschaft mit der folgenden Objektstruktur enthalten:
Der Wert der support-Eigenschaft ist ein String, der einer der folgenden sein kann:
Während eines get()-Aufrufs muss die extensions-Eigenschaft des publicKey eine largeBlob-Eigenschaft mit einem der beiden Untereigenschaften read oder write enthalten (get() schlägt fehl, wenn beide vorhanden sind):
Die read-Eigenschaft ist ein Boolescher Wert. Ein Wert von true bedeutet, dass die vertrauende Partei ein zuvor mit dem behaupteten Credential verbundenes Blob abrufen möchte:
Die write-Eigenschaft nimmt als Wert ein ArrayBuffer, TypedArray oder DataView, das ein Blob darstellt, das die vertrauende Partei zusammen mit einem vorhandenen Credential speichern möchte:
Hinweis: Damit ein Schreib-Authentifizierungsvorgang erfolgreich ist, muss das publicKey.allowCredentials nur ein einzelnes Element enthalten, das das Credential darstellt, neben dem Sie das Blob speichern möchten.
Ein erfolgreicher create()-Aufruf liefert die folgende Erweiterungsausgabe, wenn das registrierte Credential in der Lage ist, Blobs zu speichern:
Ein get()-Leseaufruf macht das Blob in der Erweiterungsausgabe als ArrayBuffer verfügbar, wenn er erfolgreich ist:
Hinweis: Wenn es fehlschlägt, wird das largeBlob-Objekt zurückgegeben, aber blob wird nicht vorhanden sein.
Ein get()-Schreibaufruf gibt an, ob der Schreibvorgang mit einem written-Booleschen Wert in der Erweiterungsausgabe erfolgreich war. Ein true-Wert bedeutet, dass es erfolgreich auf den zugehörigen Authentifikator geschrieben wurde, und false bedeutet, dass es erfolglos war.
Ermöglicht es vertrauenden Parteien, die minimale PIN-Länge des Authentikators abzufragen.
Die extensions-Eigenschaft des publicKey muss eine minPinLength-Eigenschaft mit einem Wert von true enthalten:
Wenn die vertrauende Partei autorisiert ist, den minPinLength-Wert zu erhalten (wenn ihr rpId in der autorisierten Liste der vertrauenden Parteien des Authentiksator ist), werden die Authentifikatordaten eine Darstellung dessen enthalten in folgender Form:
Wenn die vertrauende Partei nicht autorisiert ist, wird die Erweiterung ignoriert, und kein "minPinLength"-Ausgabewert wird bereitgestellt.
Ermöglicht es einer vertrauenden Partei, die Erstellung eines WebAuthn-Credentials anzufordern, das – sowohl von der vertrauenden Partei als auch von anderen Parteien – mit Secure Payment Confirmation verwendet werden kann; siehe Verwendung der sicheren Zahlungsbestätigung.
Die Eingaben für die payment-Erweiterung sind im AuthenticationExtensionsPaymentInputs dictionary definiert.
isPaymentEin Boolescher Wert, der anzeigt, dass die Erweiterung aktiv ist.
rpIDDie verlassende Parteidentifikation der verwendeten Credentials. Nur zur Authentifizierungszeit verwendet; nicht zur Registrierung.
topOriginDer Ursprung des höchstinstanzlichen Frames. Nur zur Authentifizierungszeit verwendet; nicht zur Registrierung.
payeeNameDer verwendete Name des Zahlungsempfängers, falls vorhanden, der dem Benutzer angezeigt wurde. Nur zur Authentifizierungszeit verwendet; nicht zur Registrierung.
payeeOriginDer verwendete Ursprung des Zahlungsempfängers, falls vorhanden, der dem Benutzer angezeigt wurde. Nur zur Authentifizierungszeit verwendet; nicht zur Registrierung.
totalDer dem Benutzer angezeigte Transaktionsbetrag. Nur zur Authentifizierungszeit verwendet; nicht zur Registrierung. Der Betrag hat den Typ PaymentCurrencyAmount.
instrumentDie dem Benutzer angezeigten Instrumentendetails. Nur zur Authentifizierungszeit verwendet; nicht zur Registrierung. Das Instrument hat den Typ PaymentCredentialInstrument.
Keine
Ermöglicht es einer vertrauenden Partei, Ausgaben für eines oder zwei Eingaben von einer pseudozufälligen Funktion (PRF), die mit einem Credential verknüpft ist, zu erhalten. Eine PRF ist im Grunde eine Zufallsorakel — eine Funktion, die für jede gegebene Eingabe einen zufälligen Wert zurückgibt, aber immer denselben Wert für dieselbe Eingabe liefert.
Die Fähigkeit, eine mit dem Benutzer-Credential assoziierte Zufallszahl zu generieren, ist in mehreren kryptografischen Anwendungen nützlich. Zum Beispiel kann es verwendet werden, um einen symmetrischen Schlüssel zu erzeugen, mit dem sensible Daten verschlüsselt werden, und der nur von einem Benutzer entschlüsselt werden kann, der den Seed und den zugehörigen Authentifikator besitzt. Es könnte ähnlich verwendet werden, um einen symmetrischen Schlüssel für die Ende-zu-Ende-Verschlüsselung zu erstellen, der mit einem Wert vom Server und einzigartig für dasselbe Credential und dieselbe Sitzung gesät wird.
Die Erweiterung erlaubt es Ihnen, Pufferwerte vom Typ ArrayBuffer oder TypedArray an den Authentifikator zu übergeben, der das Ergebnis der Bewertung des Wertes mit der PRF des zugehörigen Credentials zurückgibt. Dies kann in einer Behauptung im Rahmen des Authentifizierungsablaufs erfolgen — indem das Credential oder die Credentials angegeben werden, für die das Ergebnis bewertet werden soll. Es kann auch bei der Erstellung eines Credentials erfolgen; jedoch unterstützen weniger Authentikatoren die Generierung von Ausgaben bei der Erstellung von Credentials.
Während eines create()-Aufrufs kann die extensions-Eigenschaft des publicKey eine prf-Eigenschaft enthalten, die ein eval-Objekt mit der Eigenschaft first und optional der Eigenschaft second enthält. Diese Eigenschaften sind entweder ArrayBuffer oder TypedArray Instanzen, die die Werte enthalten, die an die PRF für das Credential übergeben werden sollen.
Zum Beispiel könnte die untenstehende Definition verwendet werden, um ein neues Credential zu erstellen, um einen neuen symmetrischen Schlüssel von einem vom Server bereitgestellten Geheimnis zu erstellen.
Die optionale Eigenschaft second kann verwendet werden, wenn zwei zufällige Werte für ein Credential erstellt werden müssen, wie in einem Arbeitsablauf, bei dem der Verschlüsselungscode in jeder Sitzung rotiert wird. Als Beispiel für einen solchen Arbeitsablauf geben Sie in jeder Sitzung zwei Salze weiter: das first-Salz gibt einen Wert zurück, der verwendet werden kann, um die vorherigen Sitzungsdaten zu entschlüsseln, während das second-Salz einen Wert zurückgibt, der verwendet werden kann, um diese Sitzungsdaten zu verschlüsseln. In nachfolgenden Sitzungen wird das second-Salz an die Position des first-Salzes verschoben, sodass die Lebensdauer, in der ein bestimmtes Salz sinnvoll kompromittiert werden kann, begrenzt ist.
Der create()-Aufruf kann mit den folgenden Ausnahmen abgelehnt werden:
Beachten Sie, dass die Bewertung einer PRF bei der Erstellung eines Credentials möglicherweise nicht unterstützt wird, und dies würde im Output gemeldet. Sie könnten trotzdem versuchen, die PRF in einer Behauptung, wie unten gezeigt, zu bewerten.
Während eines get()-Aufrufs kann die extensions-Eigenschaft des publicKey eine prf-Eigenschaft mit der evalByCredential-Unter-Eigenschaft enthalten. Dies ist ein Objekt, das Base64 URL-encodierte Credential-IDs mit Bewertungsobjekten mit derselben Form wie oben beschrieben abbildet. Mit anderen Worten, dies ermöglicht es, Werte für verschiedene Credentials zur Bewertung anzugeben.
Der get()-Aufruf kann mit den folgenden Ausnahmen abgelehnt werden:
NotSupportedError DomExceptionWenn eval das prf-Objekt ist oder wenn allowCredentials leer ist, wenn evalByCredential nicht leer ist.
SyntaxError DomExceptionEin beliebiger Schlüssel in evalByCredential ist der leere String oder ist keine gültige Base64 URL-Codierung, oder stimmt nicht mit der ID eines Elements mit publicKey.allowCredentials überein.
Ein erfolgreicher create()-Aufruf bietet die folgende Erweiterungsausgabe, wenn das registrierte Credential PRF bei der Erstellung von Credentials unterstützt.
Die Eigenschaft enabled gibt an, ob PRF bei der Erstellung von Credentials verwendet werden kann. Die Eigenschaften first und second enthalten das Ergebnis der Bewertung von first und second auf der Eingabe, und second wird weggelassen, wenn die entsprechende Eingabe nicht angegeben wurde.
Wenn der Authentifikator die Verwendung von PRF bei der Erstellung nicht unterstützt, sieht die Ausgabe bei create() so aus:
Ein get() gibt dasselbe prf-Objekt mit derselben Struktur wie create() zurück, außer dass es den enabled-Schlüssel weglässt. Das Objekt enthält PRF-Werte, die den Eingaben für das vom Benutzer ausgewählte Credential entsprechen.
Beachten Sie, dass enabled nur als Ausgabe für create() vorhanden ist und angibt, ob PRF vom Authentifikator unterstützt wird, wenn ein Credential erstellt wird. Wenn der Authentifikator PRF überhaupt nicht unterstützt, sieht das Ergebnis des get()-Aufrufs so aus:
| Web Authentication: An API for accessing Public Key Credentials - Level 3 # sctn-defined-extensions |
| Unknown specification # sctn-defined-extensions |
Es gibt mehrere Orte, an denen WebAuthn-Erweiterungen spezifiziert sind. IANAs WebAuthn Extension Identifiers bietet ein Register aller Erweiterungen, aber beachten Sie, dass einige veraltet sein können.
Die Kompatibilitätsdaten für WebAuthn-Erweiterungen wurden in zwei Tabellen aufgeteilt – Erweiterungen, die während der Registrierung von Anmeldeinformationen (create()) verwendet werden können, und Erweiterungen, die während der Authentifizierung (get()) verwendet werden können. Einige Erweiterungen sind während beider Vorgänge nutzbar.
JavaScript aktivieren, um diese Browser-Kompatibilitätstabelle anzuzeigen.
JavaScript aktivieren, um diese Browser-Kompatibilitätstabelle anzuzeigen.
Der Bauplan für ein besseres Internet.
Besuche die gemeinnützige Muttergesellschaft der Mozilla Corporation, die Mozilla Foundation.
Teile dieses Inhalts sind ©1998–2026 von einzelnen mozilla.org-Mitwirkenden. Inhalte sind verfügbar unter einer Creative-Commons-Lizenz.