Web Authentication Erweiterungen

Beim Aufruf von navigator.credentials.create() oder navigator.credentials.get() kann das publicKey-Objekt, das erforderlich ist, um einen WebAuthn-Fluss einzuleiten, eine extensions-Eigenschaft enthalten. Der Wert von extensions ist selbst ein Objekt, dessen Eigenschaften die Eingabewerte für alle Erweiterungen sind, die die vertrauende Partei in der aufgerufenen Methode verwenden möchte.

Hinter den Kulissen werden die Eingaben vom Benutzeragenten und/oder Authentifikator verarbeitet.

Zum Beispiel möchten wir in einem publicKey-Objekt für einen create()-Aufruf die Verwendung von zwei Erweiterungen anfordern:

1. Die credProps-Erweiterung. Vertrauende Parteien setzen credProps, um zu verlangen, dass der Browser der vertrauenden Partei mitteilt, ob das Berechtigungsnachweis nach der Registrierung ansässig/auffindbar ist. Dies ist nützlich, wenn create() mit publicKey.authenticatorSelection.residentKey = "preferred" aufgerufen wird. Um dies anzufordern, müssen Sie auch publicKey.extensions.credProps = true setzen, wenn der Browser einen Berechtigungsnachweis erstellt, und je nach verwendetem Authentifikator-Typ wird dieser auffindbar sein (zum Beispiel würde der FIDO2-Authentifikator ihn typischerweise auffindbar machen; ein FIDO1/U2F-Sicherheitsschlüssel wäre nicht auffindbar). credProps wird nur vom Benutzeragenten verarbeitet.
2. Die minPinLength-Erweiterung ermöglicht es vertrauenden Parteien, die Mindestlänge der PIN des Authentifikators abzufragen. Dies erfordert, dass extensions.minPinLength auf true gesetzt wird. minPinLength wird vom Authentifikator verarbeitet, wobei der Benutzeragent nur dient, um die Eingabedaten weiterzugeben.

const publicKey = {
  challenge: new Uint8Array([117, 61, 252, 231, 191, 241, ...]),
  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} ],
  authenticatorSelection: {
    residentKey: "preferred"
  },
  extensions: {
    credProps: true,
    minPinLength: true
  }
}

Wir können dann das publicKey-Objekt in einen create()-Aufruf übergeben, um den Berechtigungsnachweis-Erstellungsfluss zu starten:

navigator.credentials.create({ publicKey });

Wenn erfolgreich, gibt der create()-Aufruf ein Promise zurück, das mit einem PublicKeyCredential Objekt aufgelöst wird. Sobald die Erweiterungsverarbeitung abgeschlossen ist, werden die Ergebnisse der Verarbeitung in der Antwort kommuniziert (obwohl dies nicht in allen Fällen der Fall ist – es ist möglich, dass Erweiterungen keine Ausgabe haben).

navigator.credentials
  .create({ publicKey })
  .then((publicKeyCred) => {
    const myClientExtResults = publicKeyCred.getClientExtensionResults();
    // myClientExtResults will contain the output of processing
    // the "credProps" extension

    const authData = publicKeyCred.response.getAuthenticatorData();
    // authData will contain authenticator data, which will include
    // authenticator extension processing results, i.e., minPinLength
  })
  .catch((err) => {
    console.error(err);
  });

Wie das obige Code-Snippet zeigt, gibt es zwei verschiedene Stellen, an denen Sie die Ergebnisse Ihrer Erweiterungsausgabe finden können:

1. Sie können die Ergebnisse der Client- (Benutzeragenten-) Erweiterungsverarbeitung abrufen, indem Sie die Methode PublicKeyCredential.getClientExtensionResults() aufrufen. Dies gibt eine map zurück, wobei jeder Eintrag ein Erweiterungskennzeichen-String als Schlüssel und die Ausgabe von der Verarbeitung der Erweiterung durch den Client als Wert ist. Im obigen Beispiel, wenn der Browser die credProps-Erweiterung unterstützt und sie korrekt verarbeitet wurde, würde das myClientExtResults Map-Objekt einen Eintrag "credProps" mit einem Wert von { rk: true } enthalten. Dies würde bestätigen, dass das erstellte Berechtigungsnachweis tatsächlich auffindbar ist.

2. Sie können die Ergebnisse der Authentifikatorerweiterungsverarbeitung in den Authentifikatordaten für die Operation finden:

   • Bei PublicKeyCredentials, die von erfolgreichen create()-Aufrufen zurückgegeben werden, kann dies über einen Aufruf von publicKeyCredential.response.getAuthenticatorData() zurückgegeben werden.
   • Bei PublicKeyCredentials, die von erfolgreichen get()-Aufrufen zurückgegeben werden, kann dies in der publicKeyCredential.response.authenticatorData Eigenschaft gefunden werden.

   Authentifikatordaten haben die Form eines ArrayBuffer mit einer konsistenten Struktur – siehe authentifizierte Daten. Die Authentikor-Erweiterungsergebnisse werden immer in einem Abschnitt am Ende gefunden, als ein CBOR-Map, der die Ergebnisse darstellt. Siehe AuthenticatorAssertionResponse.authenticatorData für eine detaillierte Beschreibung der vollständigen Authentifikatordatenstruktur.

   Zurück zu unserem Beispiel: Wenn die vertrauende Partei autorisiert ist, den Wert minPinLength zu erhalten, würden die Authentifikatordaten eine Darstellung davon 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, von denen wir wissen, dass sie standardisiert und von mindestens einer Rendering-Engine unterstützt werden.

• Verwendbar bei: Authentifizierung (get())
• Verarbeitet von: Benutzeragent
• Spezifikation: FIDO AppID Extension (appid)

Ermöglicht es einer vertrauenden Partei, eine Bestätigung für ein zuvor registriertes Berechtigungsnachweis unter Verwendung der Legacy-FIDO U2F JavaScript-API anzufordern, um die Neu-Registrierung des Berechtigungsnachweises zu vermeiden. Das appid ist das Äquivalent zu rpId in WebAuthn (aber bedenken Sie, dass appids in Form von URLs und rpIds in Form von Domains vorliegen).

Eingabe

Die publicKey's extensions Eigenschaft muss eine appid Eigenschaft enthalten, deren Wert der Anwendungsbezeichner ist, der in der Legacy-API verwendet wurde. Zum Beispiel:

extensions: {
  appid: "https://accounts.example.com";
}

Sie müssen auch die FIDO U2F-Berechtigungsnachweis-IDs in der publicKey's allowCredentials-Eigenschaft auflisten, zum Beispiel:

allowCredentials: {
  [
    id: arrayBuffer, // needs to contain decoded binary form of id
    transports: ["nfc", "usb"]
    type: "public-key"
  ]
}

Ausgabe

Gibt appid: true aus, wenn appid für die Bestätigung erfolgreich verwendet wurde, oder appid: false andernfalls.

• Verwendbar bei: Registrierung (create())
• Verarbeitet von: Benutzeragent
• Spezifikation: FIDO AppID Exclusion Extension (appidExclude)

Ermöglicht es einer vertrauenden Partei, Authentifikatoren auszuschließen, die bestimmte zuvor unter Verwendung der Legacy-FIDO U2F JavaScript-API registrierte Berechtigungsnachweise enthalten, während der Registrierung. Dies ist erforderlich, da standardmäßig der Inhalt des excludeCredentials-Feldes als WebAuthn-Berechtigungsnachweise angesehen wird. Beim Verwenden dieser Erweiterung können Sie Legacy-FIDO U2F-Berechtigungsnachweise innerhalb von excludeCredentials einfügen, und sie werden als solche erkannt.

Eingabe

Die publicKey's extensions-Eigenschaft muss eine appidExclude-Eigenschaft enthalten, dessen Wert der Bezeichner der vertrauenden Partei ist, die die Authentifikatoren durch Legacy-FIDO U2F-Berechtigungsnachweise ausschließen möchte. Zum Beispiel:

extensions: {
  appidExclude: "https://accounts.example.com";
}

Sie können dann die FIDO U2F-Berechtigungsnachweise in der publicKey's excludeCredentials-Eigenschaft auflisten, zum Beispiel:

excludeCredentials: {
  [
    id: arrayBuffer, // needs to contain decoded binary form of id
    transports: ["nfc", "usb"]
    type: "public-key"
  ]
}

Ausgabe

Gibt appidExclude: true aus, wenn die Erweiterung durchgeführt wurde, oder appidExclude: false andernfalls.

• Verwendbar bei: Registrierung (create())
• Verarbeitet von: Benutzeragent
• Spezifikation: Credential Properties Extension (credProps)

Ermöglicht es einer vertrauenden Partei, zusätzliche Informationen/Eigenschaften über das erstellte Berechtigungsnachweis anzufordern. Dies ist derzeit nur nützlich beim Aufrufen von create() mit publicKey.authenticatorSelection.residentKey = "preferred"; es fordert Informationen an, ob das erstellte Berechtigungsnachweis auffindbar ist.

Eingabe

Die publicKey's extensions-Eigenschaft muss eine credProps-Eigenschaft mit einem Wert von true enthalten:

extensions: {
  credProps: true;
}

Sie müssen auch authenticatorSelection.requireResidentKey auf true setzen, was anzeigt, dass ein ansässiger Schlüssel erforderlich ist.

authenticatorSelection: {
  requireResidentKey: true;
}

Ausgabe

Gibt Folgendes aus, wenn das registrierte PublicKeyCredential ein clientseitig auffindbares Berechtigungsnachweis ist:

credProps: {
  rk: true;
}

Wenn rk im Output auf false gesetzt ist, handelt es sich um ein serverseitiges Berechtigungsnachweis. Wenn rk im Output nicht vorhanden ist, ist nicht bekannt, ob das Berechtigungsnachweis clientseitig auffindbar oder serverseitig ist.

• Verwendbar bei: Registrierung (create())
• Verarbeitet von: Authentifikator
• Spezifikation: Credential Protection (credProtect)

Ermöglicht es einer vertrauenden Partei, bei der Erstellung eines Berechtigungsnachweises eine minimale Berechtigungsschutzrichtlinie anzugeben.

Eingabe

Die publicKey's extensions-Eigenschaft muss eine credentialProtectionPolicy-Eigenschaft enthalten, die das Schutzniveau des zu erstellenden Berechtigungsnachweises angibt, und eine boolesche enforceCredentialProtectionPolicy-Eigenschaft, die angibt, ob der create()-Aufruf fehlschlagen soll, anstatt ein Berechtigungsnachweis zu erstellen, das nicht den angegebenen Richtlinien entspricht:

extensions: {
  credentialProtectionPolicy: "userVerificationOptional",
  enforceCredentialProtectionPolicy: true
}

Die verfügbaren credentialProtectionPolicy-Werte sind wie folgt:

"userVerificationOptional" Experimentell

Die Benutzerüberprüfung ist optional. Der äquivalente credProtect-Wert, der an den Authentifikator zur Verarbeitung gesendet wird, ist 0x01.

"userVerificationOptionalWithCredentialIDList"

Die Benutzerüberprüfung ist nur optional, wenn das Berechtigungsnachweis auffindbar ist (d.h. es ist clientseitig auffindbar). Der äquivalente credProtect-Wert, der an den Authentifikator zur Verarbeitung gesendet wird, ist 0x02.

"userVerificationRequired"

Die Benutzerüberprüfung ist immer erforderlich. Der äquivalente credProtect-Wert, der an den Authentifikator zur Verarbeitung gesendet wird, ist 0x03.

Ausgabe

Wenn der create()-Aufruf erfolgreich ist, werden die Authentifikatordaten eine Darstellung des credProtect-Werts enthalten, der die festgelegte Richtlinie in folgender Form darstellt:

{ "credProtect": 0x01 }

• Verwendbar bei: Registrierung (create()) und Authentifizierung (get())
• Verarbeitet von: Benutzeragent
• Spezifikation: Großblob-Speichererweiterung (largeBlob)

Ermöglicht es einer vertrauenden Partei, Blobs im Zusammenhang mit einem Berechtigungsnachweis auf dem Authentifikator zu speichern – zum Beispiel könnte sie wünschen, Zertifikate direkt zu speichern, anstatt einen zentralen Authentifizierungsdienst auszuführen.

Eingabe

Während eines create()-Aufrufs muss die publicKey's extensions-Eigenschaft eine largeBlob-Eigenschaft mit der folgenden Objektstruktur enthalten:

extensions: {
  largeBlob: {
    support: "required";
  }
}

Der Wert der support-Eigenschaft ist ein String, der einer der folgenden sein kann:

• "preferred": Das Berechtigungsnachweis wird mit einem Authentifikator erstellt, der Blobs speichern kann, wenn möglich, aber es wird immer noch eines erstellt, wenn nicht. Die Ausgabe-Eigenschaft „supported“ berichtet über die Fähigkeit des Authentifikators, Blobs zu speichern.
• "required": Das Berechtigungsnachweis wird mit einem Authentifikator erstellt, um Blobs zu speichern. Der create()-Aufruf schlägt fehl, wenn dies nicht möglich ist.

Während eines get()-Aufrufs muss die publicKey's extensions-Eigenschaft eine largeBlob-Eigenschaft enthalten, die eine von zwei Untereigenschaften entweder read oder write enthält (get() schlägt fehl, wenn beide vorhanden sind):

Die read-Eigenschaft ist ein boolescher Wert. Ein Wert von true gibt an, dass die vertrauende Partei ein zuvor geschriebenes Blob abrufen möchte, das mit dem behaupteten Berechtigungsnachweis verknüpft ist:

extensions: {
  largeBlob: {
    read: true;
  }
}

Die write-Eigenschaft nimmt einen Wert eines ArrayBuffer, TypedArray, oder DataView an, der ein Blob darstellt, das die vertrauende Partei alongside einem bestehenden Berechtigungsnachweis speichern möchte:

extensions: {
  largeBlob: {
    write: arrayBuffer;
  }
}

Ausgabe

Ein erfolgreicher create()-Aufruf liefert die folgende Erweiterungsausgabe, wenn das registrierte Berechtigungsnachweis in der Lage ist, Blobs zu speichern:

largeBlob: {
  supported: true; // false if it cannot store blobs
}

Ein get()-Leseaufruf macht das Blob im Erweiterungsausgang als ein ArrayBuffer verfügbar, wenn erfolgreich:

largeBlob: {
  blob: arrayBuffer;
}

Ein get()-Schreibaufruf gibt an, ob der Schreibvorgang erfolgreich war, mit einem written booleschen Wert in der Erweiterungsausgabe. Ein Wert von true bedeutet, dass es erfolgreich auf den zugehörigen Authentifikator geschrieben wurde, und false bedeutet, dass es nicht erfolgreich war.

largeBlob: {
  written: true;
}

• Verwendbar bei: Registrierung (create())
• Verarbeitet von: Authentifikator
• Spezifikation: Minimum PIN Length Extension (minPinLength)

Ermöglicht es vertrauenden Parteien, die Mindest-PIN-Länge des Authentifikators abzufragen.

Eingabe

Die publicKey's extensions-Eigenschaft muss eine minPinLength-Eigenschaft mit einem Wert von true enthalten:

extensions: {
  minPinLength: true;
}

Ausgabe

Wenn die vertrauende Partei autorisiert ist, den Wert minPinLength zu erhalten (wenn ihr rpId in der autorisierten vertrauenden Parteienliste des Authentifikators vorhanden ist), werden die Authentikatordaten eine Darstellung davon in folgender Form enthalten:

{"minPinLength": uint}

Wenn die vertrauende Partei nicht autorisiert ist, wird die Erweiterung ignoriert und kein "minPinLength"-Outputwert bereitgestellt.

• Verwendbar bei: Registrierung (create())
• Verarbeitet von: Benutzeragent
• Spezifikation: Secure Payment Confirmation

Ermöglicht es einer vertrauenden Partei, die Erstellung eines WebAuthn-Berechtigungsnachweises anzufordern, der möglicherweise – sowohl von der vertrauenden Partei als auch von anderen Parteien – mit der Secure Payment Confirmation genutzt werden kann; siehe Secure Payment Confirmation verwenden.

Eingabe

Die Eingaben für die payment-Erweiterung sind im AuthenticationExtensionsPaymentInputs Wörterbuch definiert.

isPayment

Ein boolescher Wert, der anzeigt, dass die Erweiterung aktiv ist.

rpID

Die Vertrauende Partei-ID des zu verwendenden Berechtigungsnachweises. Nur bei der Authentifizierung verwendet; nicht bei der Registrierung.

topOrigin

Der Ursprung des Top-Level-Frames. Nur bei der Authentifizierung verwendet; nicht bei der Registrierung.

payeeName

Der Name des Zahlungsempfängers, falls vorhanden, der dem Benutzer angezeigt wurde. Nur bei der Authentifizierung verwendet; nicht bei der Registrierung.

payeeOrigin

Der Ursprung des Zahlungsempfängers, falls vorhanden, der dem Benutzer angezeigt wurde. Nur bei der Authentifizierung verwendet; nicht bei der Registrierung.

total

Der Transaktionsbetrag, der dem Benutzer angezeigt wurde. Nur bei der Authentifizierung verwendet; nicht bei der Registrierung. Der Gesamtbetrag ist vom Typ PaymentCurrencyAmount.

instrument

Die Instrumentendetails, die dem Benutzer angezeigt wurden. Nur bei der Authentifizierung verwendet; nicht bei der Registrierung. Das Instrument ist vom Typ PaymentCredentialInstrument.

Ausgabe

Keine

Es gibt mehrere Orte, an denen WebAuthn-Erweiterungen spezifiziert sind. IANA's WebAuthn Extension Identifiers bietet ein Register aller Erweiterungen, aber beachten Sie, dass einige möglicherweise veraltet sind.

Orte, an denen Erweiterungen spezifiziert sind:

• Web Authentication Level 3, Section 10: Defined extensions
• Client to Authenticator Protocol (CTAP) 2, Section 12: Defined Extensions

Die Kompatibilitätsdaten für WebAuthn-Erweiterungen wurden in zwei Tabellen aufgeteilt – Erweiterungen, die während der Registrierung von Berechtigungsnachweisen (create()) verwendet werden können, und Erweiterungen, die während der Authentifizierung (get()) verwendet werden können. Einige Erweiterungen sind bei beiden Vorgängen nutzbar.