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 einloggen muss. 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 Quelle präsentiert. Dies bedeutet in der Praxis das automatische Ausfüllen verfügbarer Credentials; siehe Einloggen mit einem Passkey über das Formular-Autofill für weitere Details zur Nutzung; PublicKeyCredential.isConditionalMediationAvailable() bietet ebenfalls nützliche Informationen.

"optional"

Können Credentials für eine gegebene Operation ohne Benutzerbeteiligung übergeben werden, werden sie dies, wodurch eine automatische Wiederanmeldung ohne Benutzerbeteiligung ermöglicht wird. Ist Benutzerbeteiligung erforderlich, wird der Benutzer gebeten, sich zu authentifizieren. Dieser Wert ist für Situationen gedacht, in denen Sie mit hoher Wahrscheinlichkeit davon ausgehen können, dass ein Benutzer nicht überrascht oder verwirrt ist, wenn ein Login-Dialogfeld angezeigt wird — beispielsweise auf einer Seite, die Benutzer nicht automatisch einloggt, wenn ein Benutzer gerade auf einen "Login/Signup"-Button geklickt hat.

"required"

Der Benutzer wird immer gebeten, sich zu authentifizieren. Dieser Wert ist für Situationen gedacht, in denen Sie eine Benutzer-Authentifizierung erzwingen möchten — beispielsweise wenn Sie möchten, dass ein Benutzer sich neuanmeldet, wenn eine sensible Operation ausgeführt wird (wie die Bestätigung einer Kreditkartenzahlung) oder beim Wechsel von Benutzern.

"silent"

Der Benutzer wird nicht gebeten, sich zu authentifizieren. Die Benutzeragentur wird den Benutzer automatisch wieder authentifizieren und einloggen, wenn möglich. Sollte die Zustimmung erforderlich sein, wird das Promise mit null erfüllt. Dieser Wert ist für Situationen gedacht, in denen Sie einen Benutzer beim Besuch einer Web-App, wenn möglich, automatisch einloggen möchten, aber wenn nicht, möchten Sie ihm kein verwirrendes Login-Dialogfeld präsentieren. Stattdessen sollten Sie warten, bis der Benutzer explizit auf einen "Login/Signup"-Button klickt.

Der Standardwert ist "optional".

Hinweis: Im Falle einer Anfrage zur federated authentication (FedCM API) kann ein mediation-Wert von optional oder silent zu einem Versuch der automatischen Wiederanmeldung führen. Ob dies geschehen ist, wird dem Identitätsanbieter (IdP) über den is_auto_selected-Parameter mitgeteilt, der beim Validierungsprozess 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 Leistungsbewertungen, Sicherheitsanforderungen (der IdP möchte möglicherweise automatische Wiederanfragen ablehnen und immer Benutzerbeteiligung verlangen)

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 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 IdentityCredential-Objekt abzurufen, unter Verwendung der Federated Credential Management 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 FederatedCredential-Objekt abzurufen. Diese Schnittstelle ist mittlerweile veraltet, und Entwickler sollten die identity-Option bevorzugen, sofern verfügbar.

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

protocols

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

providers

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

otp Optional

Diese Option fordert den Browser auf, ein Einmalpasswort (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.

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

• PasswordCredential
• IdentityCredential
• FederatedCredential
• OTPCredential
• PublicKeyCredential

Wenn conditional mediation im get()-Aufruf angegeben wurde, wird der Browser-UI-Dialog angezeigt und das Promise bleibt ausstehend, bis der Benutzer ein Konto aus verfügbaren Autofill-Vorschlägen zum Anmelden auswählt:

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

Kann kein einzelnes Credential eindeutig ermittelt werden, wird das Promise mit null aufgelöst.

AbortError DOMException

Die Anfrage wurde durch einen Aufruf der abort()-Methode des mit dieser Methode verbundenen AbortController signal-Options abgebrochen.

IdentityCredentialError DOMException

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

NetworkError DOMException

Beim Anfordern eines IdentityCredential 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 Update login status using the Login Status API für weitere Informationen über den FedCM-Login-Status). In letzterem Fall kann es eine gewisse Verzögerung bei der Ablehnung geben, um zu verhindern, dass der IdP-Login-Status an den RP durchgesickert wird.

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

SecurityError DOMException

Die aufrufende Domain ist keine gültige Domain.

Vertrauende Parteien können get() mit der identity Option aufrufen, um eine Anfrage zu starten, damit sich Benutzer über einen Identitätsanbieter (IdP) bei der vertrauenden Partei anmelden, wobei Identitätsverbund verwendet wird. Ein typischer Aufruf würde so aussehen:

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

Schauen Sie sich die Federated Credential Management (FedCM) API für weitere Details an, wie dies funktioniert. Dieser Aufruf startet den Anmeldeprozess, der in FedCM sign-in flow beschrieben wird.

Ein ähnlicher Aufruf einschließlich der context und loginHint Erweiterungen 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-Assertion-Endpoint zu validieren, lehnt er das von CredentialsContainer.get() zurückgegebene Promise ab:

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);
  }
}

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-Objektinstanz aufgelöst wird, das ein public key credential darstellt, das zuvor über ein WebAuthn create() erstellt wurde und das jetzt 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, der Signatur und des Benutzerhandhabung.

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 zur Erstellung des Credentials verwendet wurde, und der userHandle, um den Benutzer mit dem Credential, dem Anmeldeversuch und anderen Daten zu verknüpfen.

Weitere Informationen darüber, wie der gesamte Prozess funktioniert, finden Sie unter Authenticating a user.

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