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, ob der Benutzer bei jedem Besuch einer Client-App zur Anmeldung aufgefordert wird. Der Wert kann einer der folgenden sein:

"conditional"

Entdeckte Credentials werden dem Benutzer in einem nicht-modalen Dialogfeld zusammen mit einem Hinweis auf die anfragende Herkunft angezeigt. Praktisch bedeutet dies das automatische Ausfüllen verfügbarer Credentials; siehe Anmelden mit einem Passkey durch Formular-Autofill für weitere Einzelheiten zu dessen Verwendung; PublicKeyCredential.isConditionalMediationAvailable() bietet ebenfalls nützliche Informationen.

"optional"

Wenn Credentials ohne Benutzermediation für eine gegebene Operation übergeben werden können, geschieht dies, was eine automatische erneute Authentifizierung ohne Benutzermediation ermöglicht. Wenn Benutzermediation erforderlich ist, wird der Benutzeragent den Benutzer bitten, sich zu authentifizieren. Dieser Wert ist für Situationen gedacht, in denen Sie berechtigten Anlass zur Annahme haben, dass ein Benutzer nicht überrascht oder verwirrt sein wird, wenn er ein Anmelde-Dialogfeld sieht — zum Beispiel auf einer Seite, 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 eine Benutzerauthentifizierung erzwingen möchten — zum Beispiel wenn Sie möchten, dass ein Benutzer sich erneut authentifiziert, wenn eine sensible Operation durchgeführt wird (wie die Bestätigung einer Kreditkartenzahlung) oder beim Wechseln von Benutzern.

"silent"

Der Benutzer wird nicht aufgefordert, sich zu authentifizieren. Der Benutzeragent wird den Benutzer automatisch erneut authentifizieren und ihn anmelden, falls möglich. Wenn eine Zustimmung erforderlich ist, wird das Promise 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, falls möglich, aber wenn nicht, möchten Sie ihnen kein verwirrendes Anmelde-Dialog anzeigen. Stattdessen möchten Sie, dass sie ausdrücklich auf einen "Login/Signup"-Button klicken.

Der Standardwert ist "optional".

Hinweis: Im Falle einer Anfrage zur föderierten Authentifizierung (FedCM API) kann ein mediation-Wert von optional oder silent zu einem Versuch der automatischen erneuten Authentifizierung führen. Ob dies geschehen ist, wird dem Identitätsanbieter (IdP) über den Parameter is_auto_selected mitgeteilt, der während der Validierung an den id_assertion_endpoint des IdP gesendet wird, und der vertrauenden Partei (RP) über die Eigenschaft IdentityCredential.isAutoSelected. Dies ist nützlich für Leistungsbewertung, Sicherheitsanforderungen (der IdP möchte möglicherweise automatische Authentifizierungsanfragen ablehnen und immer Benutzermediation verlangen), und allgemeine UX (ein IdP oder RP möchte möglicherweise eine andere UX für automatische und nicht-automatische Anmeldeerfahrungen präsentieren).

signal Optional

Eine Instanz eines AbortSignal-Objekts, die es ermöglicht, eine laufende get()-Operation abzubrechen. Eine abgebrochene Operation kann normal abgeschlossen werden (in der Regel, wenn der Abbruch nach dem Abschluss der Operation empfangen wurde) oder mit dem Grund des Signals zurückgewiesen werden (was standardmäßig ein AbortError DOMException ist oder ein benutzerdefinierter 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 abzurufen, unter Verwendung der Föderierten 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äts-Credential als ein FederatedCredential-Objekt abzurufen. Dieses Interface ist inzwischen veraltet, und Entwickler sollten die identity-Option bevorzugen, falls verfügbar.

Der Wert dieser Option ist ein Objekt mit folgenden Eigenschaften:

protocols

Ein Array von Strings, die die Protokolle der gemeinsam genutzten föderierten Identitätsanbieter der angeforderten 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 ein OTPCredential-Objekt abzurufen.

Der Wert dieser Option ist ein Array von Strings, das nur den String-Wert "sms" enthalten darf.

publicKey Optional

Diese Option fordert den Browser auf, eine mit der Web Authentication API signierte Assertion 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

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 aus den verfügbaren Autofill-Vorschlägen auswählt:

• Falls der Benutzer dann eine Geste außerhalb des Browser-UI-Dialogs macht, schließt es ohne Hinweise auf eine von Benutzer sichtbare Fehlerbedingung oder das Promise ohne Auflösung oder Ablehnung.
• Wenn der Benutzer ein Credential auswählt, wird das relevante PublicKeyCredential dem 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 AbortController abgebrochen, der mit der signal-Option dieser Methode verknüpft ist. Beachten Sie, dass wenn der Aufrufer von abort() ein reason-Argument angegeben hat, get() mit dem Wert von reason, anstelle einer AbortController-Ausnahme, abgelehnt wird.

TimeoutError DOMException

Die Anfrage wurde automatisch aufgrund eines Zeitlimits abgebrochen, das mit AbortSignal.timeout() festgelegt wurde.

IdentityCredentialError

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

NetworkError DOMException

Wenn ein IdentityCredential angefordert wird, hat der Identitätsanbieter (IdP) nicht innerhalb von 60 Sekunden geantwortet, die bereitgestellten Credentials waren nicht gültig/gefunden, oder der Login-Status des Browsers für den IdP ist auf "logged-out" gesetzt (siehe Login-Status mit der Login-Status-API aktualisieren für weitere Informationen über den FedCM-Login-Status). Im letzteren Fall kann es zu einer Verzögerung bei der Ablehnung kommen, um zu vermeiden, den Login-Status des IdP an die RP preiszugeben.

NotAllowedError DOMException

Wird in einer der folgenden Situationen ausgelöst:

• Der Benutzer hat die Anfrage abgebrochen.

• Die Verwendung dieser API wurde von einer der folgenden Permissions Policies blockiert:

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

• Der aufrufende Ursprung ist ein intransparenter Ursprung.

SecurityError DOMException

Die aufrufende Domäne ist keine gültige Domäne.

Beispiele

Abrufen eines föderierten Identitäts-Credentials

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

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

Lesen Sie den Federated Credential Management (FedCM) API für weitere Einzelheiten darüber, wie dies funktioniert. Dieser Aufruf wird den in FedCM-Anmeldefluss beschriebenen Anmeldefluss starten.

Ein ähnlicher Aufruf, der die context- und loginHint-Erweiterungen einbezieht, 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, wird das Promise, das von CredentialsContainer.get() zurückgegeben wird, 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 öffentlichen Schlüssel-Credentials

Das folgende Beispiel 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 einem PublicKeyCredential-Objekt instanziiert wird, das ein öffentliches Schlüssel-Credential darstellt, das zuvor über eine WebAuthn-create() erstellt wurde und jetzt zur Authentifizierung eines Benutzers verwendet wurde. Seine PublicKeyCredential.response-Eigenschaft enthält ein AuthenticatorAssertionResponse-Objekt, das Zugriff auf mehrere nützliche Informationen wie Authenticator-Daten, Signatur und Benutzer-Handle bietet.

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 — beispielsweise die signature, um den Nachweis zu erbringen, dass der Authenticator den echten privaten Schlüssel besitzt, der zur Erstellung des Credentials verwendet wurde, 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 folgende Code löst den Berechtigungsablauf des Browsers aus, wenn eine SMS-Nachricht eintrifft. Wenn die Erlaubnis erteilt wird, wird das Promise mit einem OTPCredential-Objekt erfüllt. Der enthaltene code-Wert wird dann als Wert eines <input>-Formular-Elements festgelegt, das 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 Zeitlimits

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 cancelled by the user.");
    } else {
      console.error("An unexpected error occurred:", err);
    }
  }
}

Spezifikationen

Browser-Kompatibilität