CredentialsContainer: `create()` Methode

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.

* Some parts of this feature may have varying levels of support.

Sicherer Kontext: Diese Funktion ist nur in sicheren Kontexten (HTTPS) in einigen oder allen unterstützenden Browsern verfügbar.

Die create() Methode der CredentialsContainer Schnittstelle erstellt ein neues Credential, welches dann gespeichert und später mithilfe der navigator.credentials.get() Methode abgerufen werden kann. Das abgerufene Credential kann dann von einer Website verwendet werden, um einen Benutzer zu authentifizieren.

Diese Methode unterstützt drei verschiedene Arten von Credentials:

  • Ein Passwort-Credential, das es einem Benutzer ermöglicht, sich mit einem Passwort anzumelden.
  • Ein föderiertes Credential, das es einem Benutzer ermöglicht, sich über einen föderierten Identitätsanbieter anzumelden.
  • Ein öffentlicher Schlüssel-Credential, das es einem Benutzer ermöglicht, sich mit einem Authenticator wie einem in die Plattform integrierten biometrischen Leser oder einem abnehmbaren Hardware-Token anzumelden.

Beachten Sie, dass die Federated Credential Management API (FedCM) den föderierten Credential-Typ ablöst.

Syntax

js
create()
create(options)

Parameter

options Optional

Ein Objekt, das Optionen für das angeforderte neue Credentials-Objekt enthält. Es kann die folgenden Eigenschaften enthalten:

signal Optional

Eine Instanz des AbortSignal Objekts, die es ermöglicht, einen laufenden create()-Vorgang abzubrechen. Ein abgebrochener Vorgang kann normal abgeschlossen werden (normalerweise, wenn der Abbruch nach Abschluss des Vorgangs empfangen wurde) oder mit einem AbortError DOMException abgelehnt werden.

Jede der folgenden Eigenschaften repräsentiert einen Credential-Typ, der erstellt wird. Einer und nur einer von ihnen muss angegeben werden:

federated Optional

Ein FederatedCredentialInit Objekt, das Anforderungen für die Erstellung eines föderierten Identitätsanbieter-Credentials enthält.

password Optional

Ein PasswordCredentialInit Objekt, das Anforderungen für die Erstellung eines Passwort-Credentials enthält.

publicKey Optional

Ein PublicKeyCredentialCreationOptions Objekt, das Anforderungen für die Erstellung eines öffentlichen Schlüssel-Credentials enthält. Bewirkt, dass der create()-Aufruf den Benutzagenten auffordert, neue Credentials über einen Authenticator zu erstellen — entweder zum Registrieren eines neuen Kontos oder zum Verknüpfen eines neuen asymmetrischen Schlüsselpaares mit einem bestehenden Konto.

Hinweis: Die Verwendung von create() mit dem Parameter publicKey kann durch eine auf Ihrem Server gesetzte publickey-credentials-create Permissions Policy blockiert werden.

Rückgabewert

Ein Promise, der mit einem der folgenden Objekte aufgelöst wird:

Falls kein Credential-Objekt erstellt werden kann, wird das Versprechen mit null aufgelöst.

Ausnahmen

TypeError

Im Fall einer PasswordCredential Erstellungsanfrage wurden id, origin oder password nicht bereitgestellt (leer).

NotAllowedError DOMException

Mögliche Ursachen umfassen:

AbortError DOMException

Der Vorgang wurde abgebrochen.

Beispiele

Erstellung eines Passwort-Credentials

Dieses Beispiel erstellt ein Passwort-Credential aus einem PasswordCredentialInit Objekt.

js
const credInit = {
  id: "1234",
  name: "Serpentina",
  origin: "https://example.org",
  password: "the last visible dog",
};

const makeCredential = document.querySelector("#make-credential");

makeCredential.addEventListener("click", async () => {
  const cred = await navigator.credentials.create({
    password: credInit,
  });
  console.log(cred.name);
  // Serpentina
  console.log(cred.password);
  // the last visible dog
});

Erstellung eines föderierten Credentials

Dieses Beispiel erstellt ein föderiertes Credential aus einem FederatedCredentialInit Objekt.

js
const credInit = {
  id: "1234",
  name: "Serpentina",
  origin: "https://example.org",
  protocol: "openidconnect",
  provider: "https://provider.example.org",
};

const makeCredential = document.querySelector("#make-credential");

makeCredential.addEventListener("click", async () => {
  const cred = await navigator.credentials.create({
    federated: credInit,
  });
  console.log(cred.name);
  console.log(cred.provider);
});

Erstellung eines öffentlichen Schlüssel-Credentials

Dieses Beispiel erstellt ein öffentliches Schlüssel-Credential aus einem PublicKeyCredentialCreationOptions Objekt.

js
const publicKey = {
  challenge: challengeFromServer,
  rp: { id: "acme.com", name: "ACME Corporation" },
  user: {
    id: new Uint8Array([79, 252, 83, 72, 214, 7, 89, 26]),
    name: "jamiedoe",
    displayName: "Jamie Doe",
  },
  pubKeyCredParams: [{ type: "public-key", alg: -7 }],
};

const publicKeyCredential = await navigator.credentials.create({ publicKey });

Der create()-Aufruf gibt, falls erfolgreich, ein Versprechen zurück, das mit einer PublicKeyCredential Objektinstanz aufgelöst wird, die ein öffentliches Schlüssel-Credential darstellt, das später verwendet werden kann, um einen Benutzer über einen WebAuthn get() Aufruf zu authentifizieren. Seine PublicKeyCredential.response Eigenschaft enthält ein AuthenticatorAttestationResponse Objekt, das Zugriff auf mehrere nützliche Informationen bietet, einschließlich der Authenticator-Daten, des öffentlichen Schlüssels, der Transportmechanismen und mehr.

js
navigator.credentials.create({ publicKey }).then((publicKeyCredential) => {
  const response = publicKeyCredential.response;

  // Access attestationObject ArrayBuffer
  const attestationObj = response.attestationObject;

  // Access client JSON
  const clientJSON = response.clientDataJSON;

  // Return authenticator data ArrayBuffer
  const authenticatorData = response.getAuthenticatorData();

  // Return public key ArrayBuffer
  const pk = response.getPublicKey();

  // Return public key algorithm identifier
  const pkAlgo = response.getPublicKeyAlgorithm();

  // Return permissible transports array
  const transports = response.getTransports();
});

Einige dieser Daten müssen auf dem Server für zukünftige Authentifizierungsvorgänge gegen dieses Credential gespeichert werden — zum Beispiel der öffentliche Schlüssel, der verwendete Algorithmus und die zulässigen Transporte.

Hinweis: Weitere Informationen darüber, wie der gesamte Ablauf funktioniert, finden Sie unter Erstellung eines Schlüsselpaares und Registrierung eines Benutzers.

Spezifikationen

Specification
Credential Management Level 1
# dom-credentialscontainer-create

Browser-Kompatibilität

BCD tables only load in the browser