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 für jeden Besuch einer Client-App einloggen muss. Der Wert kann einer der folgenden sein:

"conditional"

Entdeckte Anmeldedaten werden dem Benutzer in einem nicht-modalen Dialogfeld zusammen mit einem Hinweis auf den Ursprungsort angezeigt, der Anmeldedaten anfordert. In der Praxis bedeutet dies, dass verfügbare Anmeldedaten automatisch ausgefüllt werden; siehe Sign in with a passkey through form autofill für weitere Details, wie dies verwendet wird; PublicKeyCredential.isConditionalMediationAvailable() bietet ebenfalls nützliche Informationen.

"optional"

Falls Anmeldedaten für eine bestimmte Operation ohne Benutzermediation übergeben werden können, werden sie es, wodurch eine automatische, erneute Authentifizierung ohne Benutzermediation ermöglicht wird. Falls Benutzermediation erforderlich ist, wird der Benutzeragent den Benutzer zur Authentifizierung auffordern. Dieser Wert ist für Situationen gedacht, in denen Sie zuversichtlich sind, dass ein Benutzer nicht überrascht oder verwirrt ist, wenn er ein Anmeldedialogfeld sieht - zum Beispiel auf einer Seite, die Benutzer nicht automatisch anmeldet, wenn ein Benutzer gerade auf eine „Anmelden/Registrieren“-Schaltfläche geklickt hat.

"required"

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

"silent"

Der Benutzer wird nicht zur Authentifizierung aufgefordert. Der Benutzeragent wird den Benutzer automatisch erneut authentifizieren und anmelden, falls möglich. Wenn eine Zustimmung erforderlich ist, wird das Versprechen mit null erfüllt. Dieser Wert ist für Situationen gedacht, in denen Sie einen Benutzer automatisch anmelden möchten, wenn er eine Web-App besucht, wenn möglich, aber wenn nicht, möchten Sie ihm kein verwirrendes Anmeldedialogfeld präsentieren. Stattdessen würden Sie darauf warten, dass er ausdrücklich auf eine „Anmelden/Registrieren“-Schaltfläche klickt.

Der Standardwert ist "optional".

Hinweis: Im Falle einer föderierten Authentifizierungsanforderung (FedCM API) kann ein mediation-Wert von optional oder silent zu einem Versuch der automatischen erneuten Authentifizierung führen. Ob dies geschah, wird dem Identitätsanbieter (IdP) über den is_auto_selected-Parameter mitgeteilt, der beim Validieren an den IdP´s id_assertion_endpoint gesendet wird, und der Partei, die darauf vertraut (RP), wird dies durch die IdentityCredential.isAutoSelected-Eigenschaft mitgeteilt. Dies ist nützlich für Leistungsbewertung, Sicherheitsanforderungen (der IdP kann automatische erneute Authentifizierungsanfragen ablehnen und stets Benutzermediation verlangen) und allgemeines Benutzererlebnis (ein IdP oder RP möchte möglicherweise unterschiedliche Benutzererfahrungen für automatische und nicht-automatische Anmeldungserfahrungen präsentieren).

signal Optional

Eine Instanz eines AbortSignal-Objekts, das es ermöglicht, einen laufenden get()-Vorgang abzubrechen. Ein abgebrochener Vorgang kann normal abgeschlossen werden (in der Regel, wenn der Abbruch nach Abschluss des Vorgangs eintraf) oder mit einem AbortError DOMException abgelehnt werden.

password Optional

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

identity Optional

Diese Option fordert den Browser auf, eine föderierte Identitätsanmeldedaten als IdentityCredential Objekt abzurufen, indem die Federated Credential Management API verwendet wird.

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

federated Optional

Diese Option fordert den Browser auf, eine föderierte Identitätsanmeldedaten als FederatedCredential Objekt abzurufen. Dieses Interface wird jetzt ersetzt, und Entwickler sollten die identity-Option bevorzugen, 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 Anmeldedaten der föderierten Identitätsanbieter darstellen (zum Beispiel "openidconnect").

providers

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

otp Optional

Diese Option fordert den Browser auf, ein Einmalkennwort (OTP) als 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 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 bedingte Mediation im get()-Aufruf angegeben wurde, wird das Browser-Benutzeroberflächen-Dialogfeld angezeigt und das Versprechen bleibt schwebend, bis der Benutzer ein Konto zur Anmeldung aus den verfügbaren AutoFill-Vorschlägen auswählt:

• Wenn der Benutzer dann eine Geste außerhalb des Browser-Benutzeroberflächen-Dialogfeldes macht, schließt es sich, ohne das Versprechen aufzulösen oder abzulehnen und ohne einen benutzersichtbaren Fehlerzustand zu erzeugen.
• Wenn der Benutzer eine Anmeldedaten auswählt, wird die relevante PublicKeyCredential an den Aufrufer zurückgegeben.

Wenn eine einzelne Anmeldedaten nicht eindeutig erlangt werden kann, wird das Versprechen mit null erfüllt.

Ausnahmen

AbortError DOMException

Die Anfrage wurde durch einen Aufruf der abort() Methode des AbortController, die mit der signal-Option dieser Methode verbunden ist, abgebrochen.

IdentityCredentialError

Bei Anforderung einer IdentityCredential kann die Anfrage an den ID Assertion Endpoint nicht validiert werden und wird mit einer Fehlermeldung abgelehnt, die Informationen über den Grund enthält.

NetworkError DOMException

Bei Anforderung einer IdentityCredential hat der Identitätsanbieter (IdP) nicht innerhalb von 60 Sekunden geantwortet, die bereitgestellten Anmeldedaten waren nicht gültig/gefunden oder der Anmeldestatus des Browsers für den IdP ist auf "logged-out" gesetzt (siehe Update login status using the Login Status API für weitere Informationen über den FedCM-Anmeldestatus). Im letzten Fall kann es zu einer Verzögerung bei der Ablehnung kommen, um den Anmeldestatus des IdP nicht der RP preiszugeben.

NotAllowedError DOMException

Wird in einer der folgenden Situationen ausgelöst:

• 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 transparenter Ursprung.

SecurityError DOMException

Die aufrufende Domain ist keine gültige Domain.

Beispiele

Abrufen einer föderierten Identitätsanmeldedaten

Vertrauen schenkende Parteien können get() mit der identity-Option aufrufen, um eine Anfrage zu stellen, dass Benutzer sich bei der vertrauen schenkenden Partei über einen Identitätsanbieter (IdP) anmelden, indem Identitätsföderation verwendet wird. Eine typische Anfrage könnte so aussehen:

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

Lesen Sie mehr über Federated Credential Management (FedCM) API für weitere Details, wie dies funktioniert. Dieser Aufruf initiiert den Anmeldevorgang, der im FedCM sign-in flow beschrieben wird.

Ein ähnlicher Aufruf, einschließlich der context- und loginHint-Erweiterungen, 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: "********",
          nonce: "******",
          loginHint: "user1@example.com",
        },
      ],
    },
  });
}

Wenn der IdP eine Anfrage an den ID Assertion Endpoint nicht validieren kann, wird der Promise, der 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: "********",
            nonce: "******",
          },
        ],
      },
    });
  } 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-Anmeldedatensatzes

Das folgende Snippet 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 Versprechen zurück, das mit einem PublicKeyCredential-Objektinstanz aufgelöst wird, das eine öffentliche Schlüsselanmeldedaten darstellt, die zuvor über eine WebAuthn create() erstellt wurde und jetzt verwendet wurde, um einen Benutzer zu authentifizieren. Seine PublicKeyCredential.response-Eigenschaft enthält ein AuthenticatorAssertionResponse-Objekt, das Zugriff auf mehrere nützliche Informationen einschließlich der 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 sich der Authentifikator im Besitz des echten privaten Schlüssels befindet, der zur Erstellung der Anmeldedaten verwendet wurde, und die userHandle, um den Benutzer mit der Anmeldedaten, dem Anmeldeversuch und anderen Daten zu verknüpfen.

Siehe Authenticating a user für mehr Informationen darüber, wie der gesamte Ablauf funktioniert.

Abrufen eines Einmalkennworts

Der untenstehende Code löst den Berechtigungsablauf des Browsers aus, wenn eine SMS-Nachricht eingeht. Wenn die Erlaubnis erteilt wird, löst sich das Versprechen mit einem OTPCredential-Objekt. Der enthaltene code-Wert wird dann als Wert eines <input>-Formularelements 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);
  });

Spezifikationen

Browser-Kompatibilität