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 das Abbrechen eines laufenden create()-Vorgangs ermöglicht. Ein abgebrochener Vorgang kann normal abgeschlossen werden (in der Regel, wenn der Abbruch nach Abschluss des Vorgangs empfangen wurde) oder mit einem AbortError-DOMException fehlschlagen.

Jede der folgenden Eigenschaften repräsentiert einen zu erstellenden Credential-Typ. Es muss genau einer der Typen angegeben werden:

federated Optional

Ein FederatedCredentialInit-Objekt, das Anforderungen zum Erstellen eines Credential für einen föderierten Identitätsanbieter enthält.

password Optional

Ein PasswordCredentialInit-Objekt, das Anforderungen zum Erstellen eines Passwort-Credentials enthält.

publicKey Optional

Ein PublicKeyCredentialCreationOptions-Objekt, das Anforderungen zum Erstellen eines Public-Key-Credentials enthält. Veranlasst den create()-Aufruf, dass der User-Agent neue Credentials über einen Authenticator erstellt – 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 kann durch eine von Ihrem Server festgelegte publickey-credentials-create Permissions Policy blockiert werden.

Rückgabewert

Ein Promise, der sich mit einem der folgenden Credentials auflöst:

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

Falls kein Credential-Objekt erstellt werden kann, löst sich das Promise mit null auf.

Ausnahmen

TypeError

Im Fall eines PasswordCredential-Erstellungsantrags 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> setzt keine passende publickey-credentials-create-Policy.
• Die Funktion wird cross-origin aufgerufen und das <iframe> hat keine transient activation.
• Es wird versucht, ein discoverable credential zu erstellen (residentKey ist auf required im create()-Aufruf des PublicKeyCredentialCreationOptions-Options gesetzt), aber der Benutzer hat keinen Sicherheitsschlüssel, der discoverable credentials unterstützt, und bricht den Vorgang ab.

AbortError DOMException

Der Vorgang wurde abgebrochen.

Beispiele

Erstellen eines Passwort-Credentials

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

const credInit = {
  id: "serp1234", // "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);
  // serp1234
  console.log(cred.password);
  // the last visible dog
});

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

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, falls erfolgreich, gibt ein Promise zurück, das sich mit einer Instanz des PublicKeyCredential-Objekts auflöst, das ein Public-Key-Credential repräsentiert, welches später zur Authentifizierung eines Benutzers über einen WebAuthn-get()-Aufruf verwendet werden kann. Seine PublicKeyCredential.response-Eigenschaft enthält ein AuthenticatorAttestationResponse-Objekt, das Zugriff auf mehrere nützliche Informationen wie Authenticator-Daten, öffentlichen Schlüssel, Transportmechanismen und mehr bietet.

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 Transportmöglichkeiten.

Spezifikationen

Browser-Kompatibilität