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 an das Abrufen des Credentials beteiligt ist. Der Wert kann eines der folgenden sein:

"conditional"

Entdeckte Credentials werden dem Benutzer in einem nicht-modalen Dialogfeld zusammen mit einem Hinweis auf den Ursprung, der die Credentials anfordert, präsentiert. Praktisch bedeutet dies, dass verfügbare Credentials automatisch ausgefüllt werden; siehe Autofill-Benutzeroberfläche für weitere Details zur Nutzung.

"optional"

Wenn Credentials für eine gegebene Operation ohne Benutzermediation übergeben werden können, werden sie übergeben, was eine automatische erneute Authentifizierung ohne Benutzermediation ermöglicht. Wenn Benutzermediation erforderlich ist, fragt der Benutzeragent den Benutzer zur Authentifizierung. Dieser Wert ist für Situationen gedacht, in denen Sie berechtigte Zuversicht haben, dass ein Benutzer nicht überrascht oder verwirrt sein wird, wenn er einen Anmeldedialog sieht — zum Beispiel auf einer Website, die Benutzer nicht automatisch anmeldet, wenn ein Benutzer gerade auf eine "Login/Signup"-Schaltfläche geklickt hat.

"required"

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

"silent"

Der Benutzer wird nicht zur Authentifizierung aufgefordert. Der Benutzeragent wird den Benutzer automatisch erneut authentifizieren und anmelden, falls möglich. Falls eine Zustimmung erforderlich ist, wird das Versprechen mit null erfüllt. Dieser Wert ist für Situationen gedacht, in denen Sie einen Benutzer bei einem Besuch in einer Web-App automatisch anmelden möchten, wenn möglich. Wenn dies nicht möglich ist, sollten Sie ihn nicht mit einem verwirrenden Anmeldedialog konfrontieren, sondern vielmehr warten, bis er ausdrücklich auf eine "Login/Signup"-Schaltfläche klickt.

Der Standardwert ist "optional".

Hinweis: Im Fall einer Anfrage zur föderierten Authentifizierung (FedCM-API) kann ein mediation-Wert von optional oder silent zu einem versuchten automatischen Re-Authentifizierung führen. Ob dies geschah, wird dem Identitätsanbieter (IdP) über den is_auto_selected-Parameter mitgeteilt, der während der Validierung an den id_assertion_endpoint des IdP und über die IdentityCredential.isAutoSelected-Eigenschaft an die vertrauende Partei (RP) gesendet wird. Dies ist nützlich für die Performance-Bewertung, Sicherheitsanforderungen (der IdP könnte automatische Re-Authentifizierungsanfragen ablehnen und immer eine Benutzermediation verlangen) und allgemeine Benutzererfahrung (ein IdP oder RP könnte verschiedene Benutzererfahrungen für automatische und nicht-automatische Anmeldeerfahrungen präsentieren).

signal Optional

Eine Instanz des AbortSignal-Objekts, die es ermöglicht, eine laufende get()-Operation abzubrechen. Eine abgebrochene Operation kann normal abgeschlossen werden (im Allgemeinen, wenn der Abbruch nach Abschluss der Operation empfangen wurde) oder mit dem Grund des Signals abgelehnt werden (welches standardmäßig ein AbortError DOMException ist oder einen benutzerdefinierten Wert, wenn einer beim Aufruf von abort() angegeben wurde).

password Optional

Diese Option fordert den Browser auf, ein gespeichertes Passwort als ein PasswordCredential-Objekt abzurufen. Es ist ein boolescher Wert.

identity Optional

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

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äts-Credential als ein FederatedCredential-Objekt abzurufen. Diese Schnittstelle ist inzwischen veraltet, und Entwickler sollten die Verwendung der identity-Option bevorzugen, wenn sie verfügbar ist.

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

protocols

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

providers

Ein Array von Zeichenfolgen, 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 ein OTPCredential-Objekt abzurufen.

Der Wert dieser Option ist ein Array von Zeichenfolgen, das nur den Zeichenfolgenwert "sms" enthalten darf.

publicKey Optional

Diese Option fordert den Browser auf, eine Signatur-Aussage mithilfe der Web Authentication API als ein PublicKeyCredential abzurufen.

Der Wert dieser Option ist ein PublicKeyCredentialRequestOptions-Objekt.

Rückgabewert

Ein Promise, das mit einer der folgenden Unterklassen von Credential aufgelöst wird:

• PasswordCredential
• IdentityCredential
• FederatedCredential
• OTPCredential
• PublicKeyCredential

Falls konditionale Mediation im get()-Aufruf spezifiziert wurde, wird der Browser-UI-Dialog angezeigt und das Promise bleibt ausstehend, bis der Benutzer ein Konto aus verfügbaren Autofill-Vorschlägen zur Anmeldung auswählt:

• Wenn der Benutzer dann außerhalb des Browser-UI-Dialogs eine Geste macht, schließt es sich ohne das Promise aufzulösen oder abzulehnen und ohne einen für den Benutzer sichtbaren Fehler zu verursachen.
• Wenn der Benutzer ein Credential auswählt, wird das entsprechende PublicKeyCredential an den Aufrufer zurückgegeben.

Wenn ein einzelnes Credential nicht eindeutig erhalten werden kann, wird das Promise mit null aufgelöst.

Ausnahmen

AbortError DOMException

Die Anfrage wurde durch einen Aufruf der abort()-Methode des mit dieser Methode verbundenen AbortController-Signals abgebrochen. Beachten Sie, dass, wenn der Aufrufer von abort() ein reason-Argument bereitgestellt hat, get() mit dem Wert von reason abgelehnt wird, anstatt mit einer AbortController-Ausnahme.

TimeoutError DOMException

Die Anfrage wurde automatisch aufgrund einer festgelegten Zeitüberschreitung mit AbortSignal.timeout() abgebrochen.

IdentityCredentialError

Bei der Anfrage eines IdentityCredential kann die Anfrage an den ID Assertion Endpoint die Authentifizierung nicht validieren und lehnt mit einer Fehlerrückmeldung ab, die Informationen über den Grund enthält.

NetworkError DOMException

Bei der Anfrage eines IdentityCredential hat der Identitätsanbieter (IdP) nicht innerhalb von 60 Sekunden geantwortet, die bereitgestellten Credentials waren nicht gültig/nicht gefunden oder der Anmeldestatus des Browsers für den IdP ist auf "logged-out" gesetzt (siehe Aktualisieren des Anmeldestatuses mit der Login Status API für mehr Informationen über den FedCM Anmeldestatus). Im letzten Fall kann es zu einer Verzögerung bei der Ablehnung kommen, um zu vermeiden, dass der IdP-Anmeldestatus an die RP durchgesickert wird.

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 opaker Ursprung.

SecurityError DOMException

Die aufrufende Domain ist keine gültige Domain.

Beispiele

Abrufen eines föderierten Identitäts-Credentials

Vertrauensparteien können get() mit der identity-Option aufrufen, um eine Anfrage zu stellen, damit sich Benutzer bei der Vertrauenspartei über einen Identitätsanbieter (IdP) mithilfe der Identitätsföderation anmelden. Eine typische Anfrage sieht so aus:

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

Weitere Details zum Funktionieren finden Sie unter Federated Credential Management (FedCM) API. Dieser Aufruf startet den Anmeldeablauf, der im FedCM-Anmeldeablauf beschrieben wird.

Ein ähnlicher Aufruf, der die Erweiterungen context und loginHint umfasst, würde folgendermaßen 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, wird das von CredentialsContainer.get() zurückgegebene Versprechen abgelehnt:

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 Aufruf von get() mit der WebAuthn-Option publicKey:

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 Versprechen zurück, das mit einem PublicKeyCredential-Objektinstanz aufgelöst wird, das ein zuvor über eine WebAuthn-create() erstelltes Public Key Credential darstellt, das nun zur Authentifizierung eines Benutzers verwendet wurde. Die PublicKeyCredential.response-Eigenschaft enthält ein AuthenticatorAssertionResponse-Objekt, das Zugriff auf mehrere nützliche Informationen bietet, einschließlich der Authenticator-Daten, Signatur und Benutzer-Handle.

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 Nachweis zu erbringen, dass der Authenticator den echten privaten Schlüssel besitzt, der zum Erstellen des Credentials verwendet wurde, und das userHandle, um den Benutzer mit dem Credential, dem Anmeldeversuch und anderen Daten zu verknüpfen.

Weitere Informationen zum Ablauf der Gesamtprozesse finden Sie unter Authentifizierung eines Benutzers.

Abrufen eines Einmalpasswortes

Der untenstehende Code löst den Berechtigungsablauf des Browsers aus, wenn eine SMS-Nachricht ankommt. Wenn die Berechtigung erteilt wird, löst sich das Versprechen mit einem OTPCredential-Objekt auf. Der enthaltene code-Wert wird dann als Wert eines <input>-Formularfelds gesetzt, das dann abgeschickt 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, wenn 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 canceled by the user.");
    } else {
      console.error("An unexpected error occurred:", err);
    }
  }
}

Spezifikationen

Browser-Kompatibilität