CredentialsContainer: get()-Methode

Syntax

get()
get(options)

Parameter

options Optional

Ein Objekt, das Optionen für die Anfrage enthält. Es kann die folgenden Eigenschaften enthalten:

mediation Optional

Ein String, der angibt, wie der Benutzer in die Abrufung des Credentials eingebunden wird. Der Wert kann einer der folgenden sein:

"conditional"

Gefundene Credentials werden dem Benutzer in einem nicht modalen Dialogfeld zusammen mit einem Hinweis auf den Ursprung, der die Credentials anfordert, angezeigt. In der Praxis bedeutet dies, dass verfügbare Credentials automatisch ausgefüllt werden; siehe Autofill-UI für weitere Details zur Nutzung.

"optional"

Wenn Credentials ohne Benutzermediation für eine gegebene Operation übergeben werden können, wird dies geschehen und die automatische Re-Authentifizierung ermöglicht, ohne dass eine Benutzermediation erforderlich ist. Wenn eine Benutzermediation erforderlich ist, wird der Benutzer-Agent den Benutzer zur Authentifizierung bitten. Dieser Wert ist für Situationen gedacht, in denen Sie mit vertretbarem Vertrauen davon ausgehen können, dass ein Benutzer nicht überrascht oder verwirrt ist, wenn er ein Anmeldedialogfeld sieht — zum Beispiel auf einer Website, die Benutzer nicht automatisch anmeldet, wenn ein Benutzer gerade auf einen "Login/Signup"-Button geklickt hat.

"required"

Der Benutzer wird immer aufgefordert, sich zu authentifizieren. Dieser Wert ist für Situationen gedacht, in denen Sie die Benutzer-Authentifizierung erzwingen möchten — zum Beispiel, wenn Sie möchten, dass sich ein Benutzer erneut authentifiziert, wenn eine sensible Operation ausgeführt wird (wie die Bestätigung einer Kreditkartenzahlung) oder wenn der Benutzer gewechselt wird.

"silent"

Der Benutzer wird nicht aufgefordert, sich zu authentifizieren. Der Benutzer-Agent wird den Benutzer automatisch erneut authentifizieren und ihn wenn möglich einloggen. Wenn eine Zustimmung erforderlich ist, wird das Promise mit null erfüllt. Dieser Wert ist für Situationen gedacht, in denen Sie einen Benutzer beim Besuch einer Web-App automatisch anmelden möchten, wenn möglich, jedoch falls nicht, möchten Sie ihm kein verwirrendes Anmeldedialogfeld präsentieren. Stattdessen möchten Sie warten, bis der Benutzer explizit auf einen "Login/Signup"-Button klickt.

Der Standardwert ist "optional".

Hinweis: Im Falle einer föderierten Authentifizierungsanfrage (FedCM API) kann ein mediation-Wert von optional oder silent zu einem Versuch der automatischen Re-Authentifizierung führen. Ob dies geschehen ist, wird dem Identitätsanbieter (IdP) über den is_auto_selected-Parameter mitgeteilt, der während der Validierung an den id_assertion_endpoint des IdP gesendet wird, sowie der relying party (RP) über die IdentityCredential.isAutoSelected-Eigenschaft. Dies ist nützlich für Leistungsbewertungen, Sicherheitsanforderungen (der IdP könnte automatische Re-Authentifizierungsanfragen ablehnen und immer eine Benutzermediation verlangen) und allgemeine UX (ein IdP oder RP könnte verschiedene UX für automatische und nicht-automatische Login-Erlebnisse präsentieren wollen).

signal Optional

Eine AbortSignal-Objektinstanz, die es ermöglicht, eine laufende get()-Operation abzubrechen. Eine abgebrochene Operation kann normal beendet werden (im Allgemeinen, wenn der Abbruch nach Abschluss der Operation eingegangen ist) oder mit dem Grund des Signals abgelehnt werden (dies ist standardmäßig ein AbortError DOMException oder ein benutzerdefinierter Wert, wenn ein solcher bei Aufruf von abort() angegeben wurde).

password Optional

Diese Option fordert den Browser auf, ein gespeichertes Passwort als PasswordCredential-Objekt abzurufen. Es handelt sich um einen booleschen Wert.

identity Optional

Diese Option fordert den Browser auf, ein föderiertes Identitätscredential als IdentityCredential-Objekt abzurufen, unter Verwendung der Federated Credential Management API.

Der Wert dieser Option ist ein IdentityCredentialRequestOptions-Objekt, das Details zu den spezifischen Identitätsanbietern enthält, die die Website verwenden möchte.

federated Optional

Diese Option fordert den Browser auf, ein föderiertes Identitätscredential als FederatedCredential-Objekt abzurufen. Dieses Interface ist jetzt veraltet, und Entwickler sollten bevorzugen, die identity-Option zu verwenden, wenn sie verfügbar ist.

Der Wert dieser Option ist ein Objekt mit den folgenden Eigenschaften:

protocols

Ein Array von Strings, die die Protokolle der angeforderten föderierten Identitätsanbieter-Credentials darstellen (zum Beispiel "openidconnect").

providers

Ein Array von Strings, die die föderierten Identitätsanbieter der Credentials darstellen (zum Beispiel "https://www.facebook.com" oder "https://accounts.google.com").

otp Optional

Diese Option fordert den Browser auf, ein Einmalpasswort (OTP) als OTPCredential-Objekt abzurufen.

Der Wert dieser Option ist ein Array von Strings, welches nur den Stringwert "sms" enthalten darf.

publicKey Optional

Diese Option fordert den Browser auf, eine Signatur mit der Web Authentication API als PublicKeyCredential abzurufen.

Der Wert dieser Option ist ein PublicKeyCredentialRequestOptions-Objekt.

Rückgabewert

Ein Promise, das sich mit einer der folgenden Unterklassen von Credential auflöst:

• PasswordCredential
• IdentityCredential
• FederatedCredential
• OTPCredential
• PublicKeyCredential

Wenn konditionale Mediation im get()-Aufruf angegeben wurde, wird der Browser-UI-Dialog angezeigt und das Promise bleibt ausstehend, bis der Benutzer ein Konto zum Anmelden von den verfügbaren automatischen Ausfüllvorschlägen auswählt:

• Falls der Nutzer dann außerhalb des Browser-UI-Dialogs eine Geste macht, schließt er sich, ohne das Promise zu erfüllen oder abzulehnen, und ohne einen für den Nutzer sichtbaren Fehlerzustand zu verursachen.
• Wenn der Nutzer ein Credential auswählt, wird das relevante PublicKeyCredential dem Aufrufer zurückgegeben.

Wenn kein einzelnes Credential eindeutig gefunden werden kann, löst sich das Promise mit null auf.

Ausnahmen

AbortError DOMException

Die Anforderung wurde durch einen Aufruf der abort()-Methode des zugehörigen signal-Options des AbortController abgebrochen. Beachten Sie, dass, wenn der Aufrufer von abort() ein reason-Argument bereitgestellt hat, dann wird get() mit dem Wert von reason statt mit einer AbortController-Ausnahme abgelehnt.

TimeoutError DOMException

Die Anfrage wurde automatisch aufgrund eines durch das Aufrufen von AbortSignal.timeout() gesetzten Timeout abgebrochen.

IdentityCredentialError

Wenn eine Anfrage für ein IdentityCredential gestellt wird, kann die Anfrage an den ID Assertion Endpoint die Authentifizierung nicht validieren und lehnt ab mit einer Fehlermeldung, die Informationen über den Grund enthält.

NetworkError DOMException

Bei der Anforderung eines IdentityCredential hat der identity provider (IdP) innerhalb von 60 Sekunden nicht geantwortet, die bereitgestellten Anmeldeinformationen waren nicht gültig oder wurden nicht gefunden, oder der Anmeldestatus des Browsers für den IdP ist auf "logged-out" gesetzt (siehe Aktualisierung des Anmeldestatus mit der Login Status API für weitere Informationen über den FedCM-Anmeldestatus). Im letzteren Fall kann es zu einer Verzögerung der Ablehnung kommen, um ein Lecken des IdP-Anmeldestatus gegenüber der RP zu vermeiden.

NotAllowedError DOMException

Ausgelöst in einer der folgenden Situationen:

• Der Benutzer hat die Anfrage abgebrochen.

• Die Nutzung dieser API wurde durch eine der folgenden Berechtigungsrichtlinien blockiert:

  • identity-credentials-get
  • publickey-credentials-get
  • otp-credentials

• Der aufrufende Ursprung ist ein undurchsichtiger Ursprung.

SecurityError DOMException

Die aufrufende Domain ist nicht gültig.

Beispiele

Abrufen eines föderierten Identitätscredentials

Relying-Partien können get() mit der identity-Option aufrufen, um eine Anfrage zu stellen, bei der sich Benutzer über einen Identitätsanbieter (IdP) bei der Relying-Partei anmelden, indem sie die Identitätsföderation verwenden. Eine typische Anfrage wäre wie folgt:

async function signIn() {
  const identityCredential = await navigator.credentials.get({
    identity: {
      providers: [
        {
          configURL: "https://accounts.idp.example/config.json",
          clientId: "********",
          params: {/* IdP-specific parameters */},
        },
      ],
    },
  });
}

Für weitere Details, wie dies funktioniert, schauen Sie sich die Federated Credential Management (FedCM) API an. Dieser Aufruf startet den in FedCM-Anmeldefluss beschriebenen Anmeldefluss.

Ein ähnlicher Aufruf einschließlich der Erweiterungen context und loginHint würde wie folgt aussehen:

async function signIn() {
  const identityCredential = await navigator.credentials.get({
    identity: {
      context: "signup",
      providers: [
        {
          configURL: "https://accounts.idp.example/config.json",
          clientId: "********",
          params: {/* IdP-specific parameters */},
          loginHint: "user1@example.com",
        },
      ],
    },
  });
}

Wenn der IdP eine Anfrage an den ID Assertion Endpoint nicht validieren kann, lehnt er das von CredentialsContainer.get() zurückgegebene Promise ab:

async function signIn() {
  try {
    const identityCredential = await navigator.credentials.get({
      identity: {
        providers: [
          {
            configURL: "https://accounts.idp.example/config.json",
            clientId: "********",
            params: {/* IdP-specific parameters */},
          },
        ],
      },
    });
  } catch (e) {
    // Handle the error in some way, for example provide information
    // to help the user succeed in a future sign-in attempt
    console.error(e);
  }
}

Abrufen eines Public-Key-Credentials

Der folgende Ausschnitt zeigt einen typischen get()-Aufruf mit der WebAuthn-publicKey-Option:

const publicKey = {
  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",
};

navigator.credentials.get({ publicKey });

Ein erfolgreicher get()-Aufruf gibt ein Promise zurück, das mit einer PublicKeyCredential-Objektinstanz erfüllt wird, die ein zuvor erstelltes Public-Key-Credential über einen WebAuthn-create()-Aufruf darstellt, das jetzt zur Authentifizierung eines Benutzers verwendet wurde. Seine PublicKeyCredential.response-Eigenschaft enthält ein AuthenticatorAssertionResponse-Objekt, das Zugriff auf mehrere nützliche Informationen bietet, einschließlich der Authenticator-Daten, der Signatur und des Benutzerhandles.

navigator.credentials.get({ publicKey }).then((publicKeyCredential) => {
  const response = publicKeyCredential.response;

  // Access authenticator data ArrayBuffer
  const authenticatorData = response.authenticatorData;

  // Access client JSON
  const clientJSON = response.clientDataJSON;

  // Access signature ArrayBuffer
  const signature = response.signature;

  // Access userHandle ArrayBuffer
  const userHandle = response.userHandle;
});

Einige dieser Daten müssen auf dem Server gespeichert werden — zum Beispiel die signature, um den Beweis zu erbringen, dass der Authenticator den echten privaten Schlüssel besitzt, der verwendet wurde, um das Credential zu erstellen, und der userHandle, um den Benutzer mit dem Credential, dem Anmeldeversuch und anderen Daten zu verknüpfen.

Siehe Authentifizierung eines Benutzers für weitere Informationen darüber, wie der gesamte Ablauf funktioniert.

Abrufen eines Einmalpassworts

Der untenstehende Code löst den Berechtigungsablauf des Browsers aus, wenn eine SMS-Nachricht eintrifft. Wenn die Berechtigung erteilt wird, wird das Promise mit einem OTPCredential-Objekt erfüllt. Der enthaltene code-Wert wird dann als Wert eines <input>-Formularelements gesetzt, welches dann übermittelt wird.

navigator.credentials
  .get({
    otp: { transport: ["sms"] },
    signal: ac.signal,
  })
  .then((otp) => {
    input.value = otp.code;
    if (form) form.submit();
  })
  .catch((err) => {
    console.error(err);
  });

Implementierung eines Timeouts

In diesem Beispiel verwenden wir AbortSignal.timeout(), um die Anfrage automatisch abzubrechen, falls sie länger als 10 Sekunden dauert.

async function authenticateUser() {
  const publicKey = {
    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",
  };

  try {
    const credential = await navigator.credentials.get({
      publicKey,
      signal: AbortSignal.timeout(10000), // Abort after 10 seconds
    });
    console.log("Authentication successful:", credential);
  } catch (err) {
    if (err.name === "TimeoutError") {
      console.error("The authentication request timed out.");
    } else if (err.name === "AbortError") {
      console.log("The request was cancelled by the user.");
    } else {
      console.error("An unexpected error occurred:", err);
    }
  }
}

Spezifikationen

Browser-Kompatibilität