CredentialsContainer: Methode create()

Syntax

create()
create(options)

Parameter

options Optional

Ein Objekt mit Optionen für das angeforderte neue Credentials-Objekt. Es kann die folgenden Eigenschaften enthalten:

mediation Optional

Ein String, der angibt, wie der Benutzer an der Erstellung des Credentials beteiligt wird.

Diese Option wirkt sich nur auf Public-Key-Credentials aus. Der einzige Wert mit einer Wirkung ist "conditional". Dieser Wert bedeutet, dass der Browser versucht, das neue Credential ohne Benutzerinteraktion zu erstellen, wenn bestimmte Bedingungen erfüllt sind. Sind die Bedingungen nicht erfüllt, schlägt die Erstellung fehl. Weitere Informationen finden Sie unter Bedingte Erstellung.

signal Optional

Eine Instanz des Objekts AbortSignal, mit der sich ein laufender create()-Vorgang abbrechen lässt. Ein abgebrochener Vorgang kann normal abgeschlossen werden (in der Regel, wenn das Abbruchsignal erst nach Abschluss des Vorgangs empfangen wurde) oder mit einer AbortError-DOMException zurückgewiesen werden.

Jede der folgenden Eigenschaften steht für einen Credential-Typ, der erstellt werden soll. Genau eine davon muss angegeben werden:

federated Optional

Ein FederatedCredentialInit-Objekt mit Anforderungen für die Erstellung eines Credentials für einen föderierten Identitätsanbieter.

password Optional

Ein PasswordCredentialInit-Objekt mit Anforderungen für die Erstellung eines Passwort-Credentials.

publicKey Optional

Ein PublicKeyCredentialCreationOptions-Objekt mit Anforderungen für die Erstellung eines Public-Key-Credentials. Dadurch fordert der create()-Aufruf den User Agent auf, über einen Authenticator neue Credentials zu erstellen – entweder zur Registrierung eines neuen Kontos oder um einem bestehenden Konto ein neues asymmetrisches Schlüsselpaar zuzuordnen.

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

Rückgabewert

Ein Promise, das mit einem der folgenden Werte erfüllt 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 erfüllt.

Ausnahmen

TypeError

Bei einer Anfrage zur Erstellung eines PasswordCredential wurden id, origin oder password nicht angegeben (sind leer).

NotAllowedError-DOMException

Mögliche Ursachen sind:

• Die Verwendung wird durch eine publickey-credentials-create-Permissions Policy blockiert.
• Die Funktion wird Cross-Origin aufgerufen, aber das Attribut allow des iframes legt keine geeignete publickey-credentials-create-Richtlinie fest.
• Die Funktion wird Cross-Origin aufgerufen und das <iframe> verfügt nicht über eine transiente Aktivierung.
• Die Funktion versucht, ein auffindbares Credential zu erstellen (residentKey ist in der Option PublicKeyCredentialCreationOptions des create()-Aufrufs auf required gesetzt), aber der Benutzer verfügt über keinen Authenticator, der auffindbare Credentials unterstützt.
• Die Option mediation ist auf "conditional" gesetzt, aber die Bedingungen wurden nicht erfüllt. Weitere Informationen finden Sie unter Bedingte Erstellung.

AbortError-DOMException

Der Vorgang wurde abgebrochen.

Beispiele

Ein Passwort-Credential erstellen

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

Ein föderiertes Credential erstellen

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

Ein Public-Key-Credential erstellen

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

Bei Erfolg gibt der create()-Aufruf ein Promise zurück, das mit einer Instanz des Objekts PublicKeyCredential erfüllt wird. Diese repräsentiert ein Public-Key-Credential, das später zur Authentifizierung eines Benutzers über einen WebAuthn-get()-Aufruf verwendet werden kann. Die Eigenschaft PublicKeyCredential.response enthält ein AuthenticatorAttestationResponse-Objekt, das Zugriff auf verschiedene nützliche Informationen bietet, darunter Authenticator-Daten, den öffentlichen Schlüssel, 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 für künftige Authentifizierungsvorgänge mit diesem Credential auf dem Server gespeichert werden – beispielsweise der öffentliche Schlüssel, der verwendete Algorithmus und die zulässigen Transportmechanismen.

Ein Public-Key-Credential mit bedingter Erstellung erstellen

Dieses Beispiel verwendet die bedingte Erstellung, indem es die Option mediation auf conditional setzt. Es versucht, einen neuen Passkey ohne Benutzerinteraktion zu erstellen, wenn die für die bedingte Erstellung festgelegten Bedingungen erfüllt sind.

async function conditionalCreate(account) {
  try {
    const capabilities = await PublicKeyCredential.getClientCapabilities();
    // Only attempt conditional create if it is supported,
    // and if the user doesn't already have a passkey
    if (capabilities.conditionalCreate && !account.hasPasskey) {
      // Abort any existing WebAuthn calls
      webAuthnController.abort();

      // Get creation options, including the challenge value from the server
      const pkOptions = await getNewPasskeyOptions();
      const credential = await navigator.credentials.create({
        publicKey: pkOptions,
        mediation: "conditional",
      });
      // Conditional create succeeded: send the new credential to the server
      // for validation and storage
      await processNewPasskey(credential);
    }
  } catch (e) {
    // Ignore errors from conditional create
  }
}

Beachten Sie, dass dieses Beispiel:

• die bedingte Erstellung nur versucht, wenn der Benutzer noch keinen Passkey hat;
• alle laufenden Versuche, ein Public-Key-Credential abzurufen oder zu erstellen, vor dem Versuch der bedingten Erstellung abbricht;
• alle ausgelösten Fehler abfängt und ignoriert, beispielsweise wenn die Bedingungen nicht erfüllt wurden.

Spezifikationen

Browser-Kompatibilität