CredentialsContainer: get() Methode

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 einer Angabe des Ursprungs, der die Credentials anfordert, präsentiert. In der Praxis bedeutet dies, dass verfügbare Credentials automatisch ausgefüllt werden; siehe Sign in with a passkey through form autofill für weitere Details zur Verwendung; PublicKeyCredential.isConditionalMediationAvailable() bietet ebenfalls nützliche Informationen.

"optional"

Wenn Credentials ohne Benutzermediation für eine bestimmte Operation übergeben werden können, werden sie es, um eine automatische Reauthentifizierung ohne Benutzermediation zu ermöglichen. Wenn Benutzermediation erforderlich ist, wird die Benutzeroberfläche den Benutzer zur Authentifizierung auffordern. Dieser Wert ist für Situationen gedacht, in denen Sie vernünftigerweise annehmen, dass ein Benutzer nicht überrascht oder verwirrt sein wird, wenn er ein Anmeldedialogfeld sieht — beispielsweise auf einer Seite, die Benutzer nicht automatisch anmeldet, wenn ein Benutzer gerade die Schaltfläche „Login/Signup“ geklickt hat.

"required"

Der Benutzer wird immer zur Authentifizierung aufgefordert. Dieser Wert ist für Situationen gedacht, in denen Sie die Benutzer-Authentifizierung 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 zur Authentifizierung aufgefordert. Der Benutzer-Agent wird den Benutzer automatisch erneut authentifizieren und ihn anmelden, wenn möglich. Wenn eine Einwilligung erforderlich ist, wird das Versprechen mit null erfüllt. Dieser Wert ist für Situationen gedacht, in denen Sie einen Benutzer bei einem Web-App-Besuch automatisch anmelden möchten, wenn möglich, aber wenn nicht, möchten Sie ihm kein verwirrendes Anmeldedialogfeld präsentieren. Stattdessen sollten Sie darauf warten, dass der Benutzer explizit eine „Login/Signup“-Schaltfläche klickt.

Der Standardwert ist "optional".

Hinweis: Im Falle einer federierten Authentifizierung (FedCM API) Anfrage kann ein mediation Wert von optional oder silent eine versuchte automatische Reauthentifizierung verursachen. Ob dies geschehen ist, wird über den is_auto_selected Parameter, der an den id_assertion_endpoint des Identitätsanbieters (IdP) während der Validierung gesendet wird, und die IdentityCredential.isAutoSelected Eigenschaft der relying party (RP) mitgeteilt. Dies ist nützlich für die Leistungsevaluierung, Sicherheitsanforderungen (der IdP möchte eventuell automatische Reauthentifizierungsanforderungen ablehnen und immer eine Benutzermediation verlangen) und die allgemeine Benutzererfahrung (ein IdP oder RP möchte vielleicht unterschiedliche UX für automatische und nicht-automatische Anmeldeerfahrungen präsentieren).

signal Optional

Ein AbortSignal Objektinstanz, die es erlaubt, eine laufende get() Operation abzubrechen. Eine abgebrochene Operation kann normal abgeschlossen werden (allgemein wenn der Abbruch nach Abschluss der Operation empfangen wurde) oder mit einem AbortError DOMException abgelehnt werden.

password Optional

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

identity Optional

Diese Option fordert den Browser auf, ein federiertes Identitäts-Credential als ein IdentityCredential Objekt mit der Federated Credential Management API abzurufen.

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

federated Optional

Diese Option fordert den Browser auf, ein federiertes Identitäts-Credential als ein FederatedCredential Objekt abzurufen. Dieses Interface wurde inzwischen ersetzt und Entwickler sollten bevorzugt die identity Option 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 Credentials' federierten Identitätsanbieter repräsentieren (beispielsweise „openidconnect“).

providers

Ein Array von Strings, die die federierten Identitätsanbieter der Credentials repräsentieren (beispielsweise „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 Assertion über die Web Authentication API signiert als ein PublicKeyCredential abzurufen.

Der Wert dieser Option ist ein PublicKeyCredentialRequestOptions Objekt.

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

• PasswordCredential
• IdentityCredential
• FederatedCredential
• OTPCredential
• PublicKeyCredential

Wenn konditionelle Mediation im get() Aufruf spezifiziert wurde, wird der Browser-UI-Dialog angezeigt und das Promise bleibt schwebend, bis der Benutzer ein Konto aus den verfügbaren Autofill-Vorschlägen auswählt, um sich anzumelden:

• Wenn der Benutzer dann eine Geste außerhalb des Browser-UI-Dialogs macht, schließt dieser ohne das Versprechen aufzulösen oder abzulehnen und ohne eine benutzersichtbare Fehlermeldung zu verursachen.
• Wenn der Benutzer ein Credential auswählt, wird das relevante PublicKeyCredential dem Aufrufer zurückgegeben.

Wenn ein einzelnes Credential nicht eindeutig erhalten werden kann, löst sich das Versprechen mit null auf.

AbortError DOMException

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

IdentityCredentialError DOMException

Bei der Anforderung eines IdentityCredential ist die Anfrage an den ID Assertion Endpoint nicht in der Lage, die Authentifizierung zu validieren, und lehnt mit einer Fehlermeldung ab, die Informationen über den Grund enthält.

NetworkError DOMException

Bei der Anforderung eines IdentityCredential hat der Identitätsanbieter (IdP) nicht innerhalb von 60 Sekunden geantwortet, die bereitgestellten Credentials 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 letzteren Fall kann die Ablehnung verzögert sein, um zu vermeiden, den IdP-Anmeldestatus an die RP offenzulegen.

NotAllowedError DOMException

Geworfen in einer der folgenden Situationen:

• Der Benutzer hat die Anfrage abgebrochen.

• Die Verwendung dieser API wurde durch eine der folgenden Permissions Policies 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.

Relying-Party-Anwendungen können get() mit der identity Option aufrufen, um eine Anfrage an die Benutzer zu stellen, sich bei der Relying Party über einen Identitätsanbieter (IdP) anzumelden, 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: "******",
        },
      ],
    },
  });
}

Sehen Sie sich Federierte Credential-Management (FedCM) API für weitere Details an, wie dies funktioniert. Dieser Aufruf wird den Anmeldefluss gemäß FedCM Anmeldefluss starten.

Ein ähnlicher Aufruf, der die context und loginHint Erweiterungen einschließt, würde so 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 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: "********",
            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);
  }
}

Der folgende Codeausschnitt 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 sich mit einer PublicKeyCredential Objektinstanz auflöst, die ein zuvor über eine WebAuthn create() erstelltes Public-Key-Credential darstellt, das nun verwendet wurde, um einen Benutzer zu authentifizieren. Seine PublicKeyCredential.response Eigenschaft enthält ein AuthenticatorAssertionResponse Objekt, das Zugriff auf mehrere nützliche Informationen bietet, einschließlich der Authenticator-Daten, Signatur und Benutzerkennung.

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 verwendet wurde, um das Credential zu erstellen, und die 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.

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