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 des CredentialsContainer Interfaces erstellt ein neues Credential, das dann gespeichert und später mit 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 Public-Key-Credential, das es einem Benutzer ermöglicht, sich mit einem Authentifizierungsgerät wie einem in die Plattform eingebauten biometrischen Leser oder einem abnehmbaren Hardware-Token anzumelden.

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

Syntax

js
create()
create(options)

Parameter

options Optional

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

signal Optional

Eine AbortSignal Objektinstanz, die es ermöglicht, einen laufenden create() Vorgang abzubrechen. Ein abgebrochener Vorgang kann normalerweise abgeschlossen werden (im Allgemeinen, wenn der Abbruch nach Abschluss des Vorgangs eingegangen ist) oder mit einem AbortError DOMException abgelehnt werden.

Jede der folgenden Eigenschaften stellt einen Credential-Typ dar, der erstellt wird. Eine und nur eine von ihnen muss angegeben werden:

federated Optional

Ein FederatedCredentialInit Objekt, das Anforderungen für die Erstellung eines föderierten Anbieter-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 Public-Key-Credentials enthält. Verursacht, dass der create() Aufruf den User-Agent 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 publicKey Parameter könnte durch eine auf Ihrem Server festgelegte publickey-credentials-create Permissions Policy blockiert werden.

Rückgabewert

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

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

Ausnahmen

TypeError

Im Fall einer Anforderung zur Erstellung eines PasswordCredential wurden id, origin oder password nicht angegeben (leer).

NotAllowedError DOMException

Mögliche Ursachen sind:

AbortError DOMException

Der Vorgang wurde abgebrochen.

Beispiele

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

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

Erstellen eines Public Key Credentials

Dieses Beispiel erstellt ein Public Key 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, wenn er erfolgreich ist, ein Promise zurück, das mit einem PublicKeyCredential Objektinstanz aufgelöst wird, was ein Public Key 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: Lesen Sie Erstellen eines Schlüsselpaares und Registrieren eines Benutzers für weitere Informationen darüber, wie der gesamte Ablauf funktioniert.

Spezifikationen

Specification
Credential Management Level 1
# dom-credentialscontainer-create

Browser-Kompatibilität

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
create
publicKey option
attestation option
attestation.direct
attestation.enterprise
attestation.indirect
attestation.none
create() extensions
appidExclude extension
credProps extension
credProtect extension
Experimental
largeBlob extension
minPinLength extension
payment extension
publicKey_option.requireResidentKey
Experimental
publicKey_option.residentKey

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support
Experimental. Expect behavior to change in the future.
See implementation notes.