CredentialsContainer: create()-Methode

Syntax

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, eine laufende create()-Operation abzubrechen. Eine abgebrochene Operation kann normal abgeschlossen werden (in der Regel, wenn der Abbruch empfangen wurde, nachdem die Operation abgeschlossen war) oder mit einem AbortError DOMException zurückgewiesen werden.

Jede der folgenden Eigenschaften repräsentiert einen Credential-Typ, der erstellt wird. Nur eine von ihnen muss angegeben werden:

federated Optional

Ein FederatedCredentialInit-Objekt, das Anforderungen für die Erstellung eines federierten 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 public key-Credentials enthält. Veranlasst den create()-Aufruf, dass der User-Agent neue Credentials über einen Authenticator erstellt — entweder zur Registrierung eines neuen Kontos oder zur Verknüpfung eines neuen asymmetrischen Schlüsselpaares mit einem bestehenden Konto.

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

Rückgabewert

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

• Ein FederatedCredential, falls der Credential-Typ federated war.
• Ein PasswordCredential, falls der Credential-Typ password war.
• Ein PublicKeyCredential, falls der Credential-Typ publicKey war.

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

Ausnahmen

TypeError

Bei der Anforderung zur Erstellung eines PasswordCredential wurden id, origin oder password nicht angegeben (leer).

NotAllowedError DOMException

Mögliche Ursachen:

• Die Nutzung wurde durch eine publickey-credentials-create Permissions Policy blockiert.
• Die Funktion wird Cross-Origin aufgerufen, aber das iframe-Element hat kein geeignetes publickey-credentials-create-Policy in seinem allow-Attribut festgelegt.
• Die Funktion wird Cross-Origin aufgerufen und das <iframe> hat keine transient activation.
• Die Funktion hat versucht, ein discoverable credential zu erstellen (residentKey ist in den create()-Aufruf-Optionen auf required gesetzt), aber der Benutzer hat keinen Authenticator, der discoverable credentials unterstützt.

AbortError DOMException

Der Vorgang wurde abgebrochen.

Beispiele

Erstellen eines Passwort-Credentials

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

const credInit = {
  id: "serpent1234", // "username" in a typical username/password pair
  name: "Serpentina", // display name for credential
  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.id);
  // serpent1234
  console.log(cred.password);
  // the last visible dog
});

Erstellen eines federierten Credentials

Dieses Beispiel erstellt ein federiertes Credential aus einem FederatedCredentialInit-Objekt.

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.

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 Promise zurück, das mit einer PublicKeyCredential-Objektinstanz aufgelöst wird, die 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 public keys, der Transportmechanismen und mehr.

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 gespeichert werden, um zukünftige Authentifizierungsoperationen gegen dieses Credential durchzuführen — zum Beispiel der public key, der verwendete Algorithmus und die zulässigen Übertragungen.

Spezifikationen

Browser-Kompatibilität