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 Anmeldedaten werden dem Benutzer in einem nicht-modalen Dialogfeld präsentiert, zusammen mit einem Hinweis auf den Ursprung der Anfrage. In der Praxis bedeutet dies das automatische Ausfüllen verfügbarer Anmeldedaten; siehe Anmelden mit einem Passkey über Formular-Autofill für weitere Details, wie dies verwendet wird; PublicKeyCredential.isConditionalMediationAvailable() bietet ebenfalls einige nützliche Informationen.

• "optional": Wenn Anmeldedaten für eine gegebene Operation ohne Benutzerbeteiligung übergeben werden können, werden sie es, wodurch eine automatische Reauthentifizierung ohne Benutzerbeteiligung ermöglicht wird. Wenn Benutzerbeteiligung erforderlich ist, wird der Benutzeragent den Benutzer zur Authentifizierung auffordern. Dieser Wert ist für Situationen gedacht, in denen Sie mit angemessener Sicherheit davon ausgehen können, dass ein Benutzer nicht überrascht oder verwirrt sein wird, ein Anmeldedialogfeld zu sehen — zum Beispiel auf einer Seite, die Benutzer nicht automatisch einloggt, wenn ein Benutzer gerade auf eine "Anmelden/Registrieren"-Schaltfläche geklickt hat.

• "required": Der Benutzer wird immer zur Authentifizierung aufgefordert, auch wenn das Verhindern von stillem Zugriff (siehe CredentialsContainer.preventSilentAccess()) auf false gesetzt ist. Dieser Wert ist für Situationen gedacht, in denen Sie eine Benutzer-Authentifizierung erzwingen möchten — zum Beispiel, wenn Sie möchten, dass ein Benutzer sich bei einer sensiblen Operation (wie der Bestätigung einer Kreditkartenzahlung) oder beim Wechseln von Benutzern erneut authentifiziert.

• "silent": Der Benutzer wird nicht zur Authentifizierung aufgefordert. Der Benutzeragent wird den Benutzer automatisch erneut authentifizieren und einloggen, wenn möglich. Wenn eine Zustimmung erforderlich ist, wird die Promise mit null erfüllt. Dieser Wert ist für Situationen gedacht, in denen Sie einen Benutzer beim Besuch einer Web-App automatisch einloggen möchten, wenn möglich, aber wenn nicht, möchten Sie ihm kein verwirrendes Anmeldedialogfeld präsentieren. Stattdessen möchten Sie warten, bis er explizit auf eine "Anmelden/Registrieren"-Schaltfläche klickt.

Der Standardwert ist "optional".

Hinweis: Im Falle einer föderierten Authentifizierungsanfrage (FedCM API) kann ein mediation-Wert von optional oder silent zu einem Versuch der automatischen Reauthentifizierung führen. Ob dies erfolgt ist, wird dem Identitätsanbieter (IdP) über den is_auto_selected-Parameter, der an den id_assertion_endpoint des IdP während der Validierung gesendet wird und der auf den IdentityCredential.isAutoSelected-Eigenschaft des relying party (RP) kommuniziert. Dies ist nützlich für die Leistungsevaluation, Sicherheitsanforderungen (der IdP möchte möglicherweise automatische Reauthentifizierungsanfragen ablehnen und immer Benutzerbeteiligung verlangen) und allgemeine Benutzererfahrung (ein IdP oder RP möchte möglicherweise unterschiedliche Benutzererfahrungen für automatische und nicht-automatische Anmeldung bieten).

signal Optional

Eine AbortSignal-Objektinstanz, 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 ist ein boolescher Wert.

identity Optional

Diese Option fordert den Browser auf, ein föderiertes Identitätsanmeldediel als ein IdentityCredential-Objekt mit Hilfe der Föderierten Anmeldemanagement API abzurufen.

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 föderiertes Identitätsanmeldedaten als ein FederatedCredential-Objekt abzurufen. Dieses Interface ist nun veraltet, 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 Anmeldedaten der föderierten Identitätsanbieter darstellen (zum Beispiel "openidconnect").

providers

Ein Array von Strings, das die föderierten Identitätsanbieter der Anmeldedaten 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 kann.

publicKey Optional

Diese Option fordert den Browser auf, eine Web-Authentifizierung-Assertion 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 ein einzelnes Anmeldedaten nicht eindeutig erhalten werden kann, wird die Promise mit null aufgelöst.

AbortError DOMException

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

IdentityCredentialError DOMException

Bei einer Anfrage nach einem 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 einer Anfrage nach einem IdentityCredential hat der Identitätsanbieter (IdP) nicht innerhalb von 60 Sekunden geantwortet, die bereitgestellten Anmeldedaten waren ungültig/nicht gefunden oder der Login-Status des Browsers für den IdP ist auf "logged-out" gesetzt (siehe Aktualisierung des Login-Status mithilfe der Login-Status-API für weitere Informationen zum FedCM-Login-Status). Im letzteren Fall kann es zu einer Verzögerung bei der Ablehnung kommen, um zu vermeiden, dass der IdP-Login-Status an die RP weitergegeben wird.

NotAllowedError DOMException

Wird in einer der folgenden Situationen ausgelöst:

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

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

Schauen Sie sich den Föderierten Anmeldungsmanagement (FedCM) API für weitere Details an, wie dies funktioniert. Dieser Aufruf wird den Anmeldefluss starten, der im FedCM-Anmeldefluss beschrieben wird.

Ein ähnlicher Aufruf, der die context- und loginHint-Erweiterungen beinhaltet, 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, wird er die Promise ablehnen, die von CredentialsContainer.get() zurückgegeben wird:

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 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 eine Promise zurück, die mit einem PublicKeyCredential-Objektinstanz aufgelöst wird, das ein zuvor über einen WebAuthn-create()](/de/docs/Web/API/CredentialsContainer/create) erstelltes Public-Key-Anmeldedaten darstellt, das nun 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 Authentifikator-Daten, der Signatur und des Benutzer-Handles.

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

Ein Teil dieser Daten muss auf dem Server gespeichert werden — beispielsweise die signature, um den Beweis zu erbringen, dass der Authentifikator den echten privaten Schlüssel besitzt, der zur Erstellung des Anmeldedaten verwendet wurde, und der userHandle, um den Benutzer mit den Anmeldedaten, dem Anmeldeversuch und anderen Daten zu verknüpfen.

Siehe Authentifizierung eines Benutzers für weitere Informationen darüber, wie der Gesamtprozess funktioniert.

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