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 (im Allgemeinen, wenn der Abbruch nach Abschluss der Operation empfangen wurde) oder mit einem AbortError-DOMException fehlschlagen.

Jede der folgenden Eigenschaften stellt einen zu erstellenden Credential-Typ dar. 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 Public Key Credentials enthält. Veranlasst den create()-Aufruf, dass der Benutzeragent neue Credentials über einen Authentifikator erstellt — entweder für die Registrierung eines neuen Kontos oder für die Verknüpfung eines neuen asymmetrischen Schlüsselpaares mit einem bestehenden Konto.

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

Rückgabewert

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

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

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

Ausnahmen

TypeError

Im Falle einer Erstellung eines PasswordCredential-Antrags, wurden id, origin oder password nicht bereitgestellt (leer).

NotAllowedError DOMException

Mögliche Ursachen sind:

• Die Nutzung wurde durch eine publickey-credentials-create Permissions Policy blockiert.
• Die Funktion wird cross-origin aufgerufen, aber das allow-Attribut des <iframe>s setzt keine passende publickey-credentials-create-Richtlinie.
• Die Funktion wird cross-origin aufgerufen und das <iframe> hat keine transiente Aktivierung.
• Es wird versucht, ein entdeckbares Credential zu erstellen (residentKey ist in der create()-Aufrufoption PublicKeyCredentialCreationOptions auf required gesetzt), aber der Benutzer hat keinen Sicherheitsschlüssel, der entdeckbare Credentials unterstützt, und bricht den Vorgang ab.

AbortError DOMException

Die Operation wurde abgebrochen.

Beispiele

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

Erstellung eines föderierten Credentials

Dieses Beispiel erstellt ein föderiertes 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);
});

Erstellung 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, wenn erfolgreich, gibt ein Promise zurück, das mit einem PublicKeyCredential-Objektinstanz aufgelöst wird, das ein Public Key Credential darstellt, das später über einen WebAuthn-get()-Aufruf zur Authentifizierung eines Benutzers verwendet werden kann. Seine PublicKeyCredential.response-Eigenschaft enthält ein AuthenticatorAttestationResponse-Objekt, das Zugriff auf mehrere nützliche Informationen bietet, einschließlich der Authentifikatordaten, des öffentlichen Schlüssels, 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 für künftige Authentifizierungsvorgänge gegen dieses Credential gespeichert werden — beispielsweise der öffentliche Schlüssel, der verwendete Algorithmus und die zulässigen Transports.

Spezifikationen

Browser-Kompatibilität