PublicKeyCredential: Statische Methode getClientCapabilities()

Syntax

PublicKeyCredential.getClientCapabilities()

Parameter

Keine.

Rückgabewert

Ein Promise, das mit einem Objekt erfüllt wird. Die Eigenschaftsnamen des Objekts sind die Zeichenfolgen für Client-Funktionen; die Werte sind boolesche Werte, die angeben, ob die jeweilige Funktion oder Erweiterung unterstützt wird.

Die Zeichenfolgen für WebAuthn-Client-Funktionen sind:

"conditionalCreate"

Der Client unterstützt conditional create. Beachten Sie, dass isConditionalMediationAvailable() nicht angibt, ob conditional create unterstützt wird.

"conditionalGet"

Der Client unterstützt conditional get. Diese Funktion entspricht einem Rückgabewert von true für isConditionalMediationAvailable().

"hybridTransport"

Der Client unterstützt die Verwendung des hybrid-Transports. Das bedeutet, dass der Client Authentifikatoren verwenden kann, die Bluetooth, NFC oder USB nutzen.

"passkeyPlatformAuthenticator"

Der Client erlaubt die Verwendung eines Passkey-Authentifikators, der Mechanismen zur Multi-Faktor-Authentifizierung wie eine PIN oder eine biometrische Prüfung unterstützt. Der Authentifikator kann Teil derselben Plattform (desselben Geräts) wie der Client oder über einen hybrid-Transport wie Bluetooth oder USB verbunden sein. Die Anmeldedaten werden auf dem Authentifikator gespeichert. Weitere Informationen finden Sie im Entwicklerleitfaden zu Passkeys für Relying Parties.

userVerifyingPlatformAuthenticator

Der Client verfügt über einen Plattform-Authentifikator (als Teil desselben Geräts), der Mechanismen zur Multi-Faktor-Authentifizierung wie eine PIN oder eine biometrische Prüfung unterstützt. Die Anmeldedaten können entweder bei der RP oder auf dem Authentifikator gespeichert werden.

relatedOrigins

Der Client unterstützt Related Origin Requests. Diese Clients ermöglichen es, einen Passkey über mehrere Websites hinweg zu verwenden, die denselben Origin haben.

signalAllAcceptedCredentials

Der Client unterstützt die statische Methode PublicKeyCredential.signalAllAcceptedCredentials(). Falls sie nicht unterstützt wird, müssen RP-Abläufe die Benutzer auffordern, Anmeldedaten auf dem Authentifikator manuell zu löschen.

signalCurrentUserDetails

Der Client unterstützt die statische Methode PublicKeyCredential.signalCurrentUserDetails(). Falls sie nicht unterstützt wird, müssen RP-Abläufe die Benutzer auffordern, Benutzerdaten auf dem Authentifikator manuell zu aktualisieren.

signalUnknownCredential

Der Client unterstützt die statische Methode PublicKeyCredential.signalUnknownCredential(). Falls sie nicht unterstützt wird, müssen RP-Abläufe die Benutzer auffordern, Anmeldedaten manuell vom Authentifikator zu löschen.

Die Zeichenfolgen für WebAuthn-Erweiterungen werden gebildet, indem dem Erweiterungsbezeichner das Präfix extension: vorangestellt wird. Beispielsweise kann mit dem Schlüssel extension:appid geprüft werden, ob die appid-Erweiterung unterstützt wird.

Ausnahmen

Das zurückgegebene Promise kann mit den folgenden Werten abgelehnt werden:

SecurityError DOMException

Die Domain der RP ist ungültig.

Beschreibung

Mit getClientCapabilities() können Sie prüfen, ob eine bestimmte Funktion oder Erweiterung unterstützt wird, und anhand dieser Information eine passende Benutzererfahrung bereitstellen.

Die Unterstützung der Funktion userVerifyingPlatformAuthenticator zeigt beispielsweise an, dass biometrische Verfahren wie ein Fingerabdrucksensor zulässig sind. Eine Webanwendung könnte damit ein Fingerabdrucksymbol anzeigen, wenn die Funktion unterstützt wird, andernfalls aber ein Eingabefeld für ein Passwort. Wenn eine biometrische Anmeldung erforderlich ist, könnte sie stattdessen darauf hinweisen, dass eine Authentifizierung auf der Website mit diesem Browser oder Gerät nicht möglich ist. Entsprechend zeigt conditionalGet an, dass der Client bei der Anmeldung eines Benutzers conditional mediation unterstützt. Das bedeutet, dass der Browser in einem Anmeldeformular automatisch ausgefüllte, auffindbare Anmeldedaten bereitstellen kann (beispielsweise in einem Texteingabefeld mit automatischer Vervollständigung oder einer Dropdown-Liste), zusammen mit einer Anmeldeschaltfläche.

Wenn der Wert einer bestimmten Funktion im zurückgegebenen Objekt vorhanden ist, gibt true an, dass die Funktion derzeit unterstützt wird, und false, dass sie nicht unterstützt wird. Fehlt jedoch der Schlüssel für eine bestimmte Funktion, lässt sich daraus keine Aussage über die Verfügbarkeit der zugehörigen Funktion ableiten.

Für Erweiterungen gelten dieselben Annahmen. Beachten Sie jedoch: Auch wenn der Client eine Erweiterung unterstützt, muss ein bestimmter Authentifikator sie nicht unterstützen. RPs dürfen daher nicht davon ausgehen, dass die Verarbeitungsschritte des Authentifikators für diese Erweiterung durchgeführt werden. Fehlt der Schlüssel für eine Erweiterung, kann eine RP weder davon ausgehen, dass dieser Client die Verarbeitungsschritte für die Erweiterung ausführt, noch davon, dass die Erweiterung an den Authentifikator weitergeleitet wird.

Beispiele

Alle Funktionen prüfen

Dieses Beispiel zeigt, wie Sie das Objekt mit den Funktionen abrufen und über seine Werte iterieren.

<pre id="log"></pre>

const logElement = document.querySelector("#log");
function log(text) {
  logElement.innerText = `${logElement.innerText}${text}\n`;
  logElement.scrollTop = logElement.scrollHeight;
}

#log {
  height: 230px;
  overflow: scroll;
  padding: 0.5rem;
  border: 1px solid black;
}

JavaScript

Zunächst warten wir auf getClientCapabilities(), um ein Objekt mit den Funktionen zu erhalten. Anschließend iterieren wir über das Objekt und protokollieren das Ergebnis (der Code für die Protokollierung ist nicht dargestellt):

async function checkClientCapabilities() {
  const capabilities = await PublicKeyCredential.getClientCapabilities();

  if (capabilities) {
    log("Client Capabilities:");

    for (const [key, value] of Object.entries(capabilities)) {
      log(` ${key}: ${value}`);
    }
  }
}

Bevor wir die Funktion aufrufen, prüfen wir, ob sie definiert ist, und protokollieren das Ergebnis.

// Call the function to check capabilities.
if (PublicKeyCredential.getClientCapabilities) {
  checkClientCapabilities();
} else {
  log(
    "PublicKeyCredential.getClientCapabilities() is not supported on this browser.",
  );
}

Ergebnis

Auf einen benutzerverifizierenden Plattform-Authentifikator prüfen

Dieses Beispiel prüft eine einzelne Funktion: userVerifyingPlatformAuthenticator. Eine reale Anwendung könnte das Ergebnis nutzen, um die Benutzeroberfläche zu konfigurieren.

<pre id="log"></pre>

const logElement = document.querySelector("#log");
function log(text) {
  logElement.innerText = `${logElement.innerText}${text}\n`;
  logElement.scrollTop = logElement.scrollHeight;
}

#log {
  height: 40px;
  overflow: scroll;
  padding: 0.5rem;
  border: 1px solid black;
}

JavaScript

Der Code ähnelt dem vorherigen Beispiel. Allerdings prüfen wir eine bestimmte zurückgegebene Funktion und verwenden try...catch, um den Fall abzufangen, dass getClientCapabilities() nicht unterstützt wird.

checkIsUserVerifyingPlatformAuthenticatorAvailable();

async function checkIsUserVerifyingPlatformAuthenticatorAvailable() {
  try {
    const capabilities = await PublicKeyCredential.getClientCapabilities();

    if (capabilities.userVerifyingPlatformAuthenticator) {
      log("Biometric login supported");
    } else {
      log("Biometric login not supported. Do password.");
    }
  } catch (error) {
    if (error instanceof TypeError) {
      log(
        "PublicKeyCredential.getClientCapabilities() is not supported on this browser.",
      );
    } else {
      log(`Unexpected error: ${error}`);
    }
  }
}

Beachten Sie, dass wir hier das Ergebnis einer Prüfung protokollieren. In einer realen Anwendung könnten wir die Benutzeroberfläche aktualisieren, um geeignete Optionen zur Verifizierung des Benutzers anzuzeigen.

Ergebnis

Das nachfolgende Protokoll zeigt entweder eine Zeichenfolge an, die darauf hinweist, dass die Methode nicht unterstützt wird, oder eine, die angibt, ob die biometrische Anmeldung oder die Anmeldung mit Passwort unterstützt wird.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Web Authentication API