CredentialsContainer: get() Methode

options Optional

Ein Objekt, das Optionen für die Anfrage enthält. Es kann folgende 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 das automatische Ausfüllen verfügbarer Credentials; siehe Mit einem Zeigeschlüssel durch automatisches Ausfüllen des Formulars anmelden für weitere Details zur Verwendung; PublicKeyCredential.isConditionalMediationAvailable() bietet ebenfalls hilfreiche Informationen.

"optional"

Wenn Credentials ohne Benutzermediation für eine bestimmte Operation übergeben werden können, wird dies geschehen, was eine automatische Reauthentifizierung ohne Benutzermediation ermöglicht. Wenn Benutzermediation erforderlich ist, wird der Benutzeragent den Benutzer um Authentifizierung bitten. Dieser Wert ist für Situationen gedacht, in denen Sie mit angemessener Sicherheit davon ausgehen können, dass ein Benutzer nicht überrascht oder verwirrt ist, wenn er ein Login-Dialogfeld sieht — zum Beispiel auf einer Website, die Benutzer nicht automatisch anmeldet, wenn ein Benutzer gerade auf eine "Login/Anmelden"-Schaltfläche geklickt hat.

"required"

Der Benutzer wird immer aufgefordert, sich zu authentifizieren. Dieser Wert ist für Situationen vorgesehen, in denen Sie die Benutzerauthentifizierung erzwingen möchten — zum Beispiel, wenn Sie möchten, dass ein Benutzer sich neu authentifiziert, wenn eine sensible Operation ausgeführt wird (wie das Bestätigen einer Kreditkartenzahlung) oder wenn Benutzer gewechselt werden.

"silent"

Der Benutzer wird nicht zur Authentifizierung aufgefordert. Der Benutzeragent wird den Benutzer, wenn möglich, automatisch erneut authentifizieren und anmelden. Wenn 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. Wenn nicht, möchten Sie ihm kein verwirrendes Login-Dialogfeld anzeigen. Stattdessen sollten Sie warten, bis er ausdrücklich auf eine "Login/Anmelden"-Schaltfläche klickt.

Der Standardwert ist "optional".

Hinweis: Im Fall einer federierten Authentifizierung (FedCM API)-Anfrage kann ein mediation Wert von optional oder silent zu einem Versuch der automatischen Reauthentifizierung 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, und der vertrauenden Partei (RP) über die IdentityCredential.isAutoSelected Eigenschaft. Dies ist nützlich für die Leistungsevaluation, Sicherheitsanforderungen (der IdP möchte möglicherweise automatische Reauthentifizierungsanforderungen ablehnen und immer Benutzermediation verlangen) und allgemeine UX (ein IdP oder RP könnte unterschiedliche UX für automatische und nicht-automatische Login-Erfahrungen präsentieren wollen).

signal Optional

Ein AbortSignal Objekt, das 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 einem AbortError DOMException abgelehnt werden.

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 federiertes Identitäts-Credential als ein IdentityCredential Objekt abzurufen, unter Verwendung der FedCM API.

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, ein federiertes Identitäts-Credential als ein FederatedCredential Objekt abzurufen. Diese Schnittstelle ist jetzt veraltet, und Entwickler sollten bevorzugt die identity Option verwenden, wenn diese verfügbar ist.

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

protocols

Ein Array von Strings, das die Protokolle der angeforderten federierten Identitätsanbieter-Credentials repräsentiert (zum Beispiel "openidconnect").

providers

Ein Array von Strings, das die federierten Identitätsanbieter der Credentials repräsentiert (zum Beispiel "https://www.facebook.com" oder "https://accounts.google.com").

otp Optional

Diese Option fordert den Browser auf, ein Einmal-Passwort (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 Behauptung, die unter Verwendung der Web Authentication API signiert wurde, als ein PublicKeyCredential abzurufen.

Der Wert dieser Option ist ein PublicKeyCredentialRequestOptions Objekt.

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

• PasswordCredential
• IdentityCredential
• FederatedCredential
• OTPCredential
• PublicKeyCredential

Wenn conditionale Mediation im get() Aufruf angegeben wurde, wird der Browser-UI-Dialog angezeigt und das Promise bleibt ausstehend, bis der Benutzer ein Konto für die Anmeldung aus den verfügbaren Autovervollständigungsvorschlägen auswählt:

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

Wenn kein einzelnes Credential eindeutig abgerufen werden kann, wird das Promise mit null aufgelöst.

AbortError DOMException

Die Anfrage wurde durch einen Aufruf der abort() Methode des mit dieser Methode assoziierten AbortController über die signal Option abgebrochen.

IdentityCredentialError DOMException

Beim Anfordern eines IdentityCredential konnte die Anfrage an den ID Behauptungsendpunkt die Authentifizierung nicht validieren und wird mit einer Fehlermeldung abgelehnt, die Informationen über den Grund enthält.

NetworkError DOMException

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

NotAllowedError DOMException

Wird in einer der folgenden Situationen ausgelöst:

• Der Benutzer hat die Anfrage abgebrochen.

• Die Verwendung 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 Domäne ist keine gültige Domäne.

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) anmelden, unter Verwendung einer Identitätsföderation. 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 die Federated Credential Management (FedCM) API für detailliertere Informationen an. Dieser Aufruf startet den Anmeldevorgang, der im FedCM Anmeldefluss beschrieben wird.

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 nicht in der Lage ist, eine Anfrage an den ID Behauptungsendpunkt zu validieren, 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 mit einem PublicKeyCredential Objektinstanz aufgelöst wird, welches 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 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 nachzuweisen, dass der Authenticator den echten privaten Schlüssel besitzt, der verwendet wird, um das Credential zu erstellen, und die userHandle, um den Benutzer mit dem Credential, dem Anmeldeversuch und anderen Daten zu verknüpfen.

Sehen Sie sich Authentifizierung eines Benutzers für weitere Informationen an, 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 aufgelöst. Der enthaltene code Wert wird dann als Wert eines <input> Formularelements festgelegt, das anschließend ü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);
  });