CredentialsContainer: create() method
MDN Web Docs · نسخهٔ df622a2a1c1e · CC BY-SA 2.5 و مجوز جداگانهٔ ناشر برای نمونهکد
{{APIRef("Credential Management API")}}{{SecureContext_Header}}
The **create()** method of the {{domxref("CredentialsContainer")}} interface creates a new {{glossary("credential")}}, which can then be stored and later retrieved using the {{domxref("CredentialsContainer.get", "navigator.credentials.get()")}} method. The retrieved credential can then be used by a website to authenticate a user.
This method supports three different types of credential:
- A password credential, which enables a user to sign in using a password.
- A federated credential, which enables a user to sign in using a federated identity provider. Note that the Federated Credential Management API (FedCM) supersedes the federated credential type.
- A public key credential, which enables a user to sign in with an authenticator such as a biometric reader built into the platform or a removable hardware token. Passkeys are a type of public key credential.
Syntax
create()
create(options)Parameters
options{{optional_inline}}- : An object that contains options for the requested new
Credentialsobject. It can contain the following properties: mediation{{optional_inline}}- : A string indicating how the user is involved in creating the credential.
This option only has an effect for public key credentials, and the only value that has an effect is "conditional". This value means that if certain conditions are met, then the browser will attempt to create the new credential without requiring any user interaction. If the conditions are not met, creation will fail. See Conditional create for more details.
signal{{optional_inline}}- : An {{domxref("AbortSignal")}} object instance that allows an ongoing
create()operation to be aborted. An aborted operation may complete normally (generally if the abort was received after the operation finished) or reject with anAbortError{{domxref("DOMException")}}.
Each of the following properties represents a _credential type_ being created. One and only one of them must be specified:
federated{{optional_inline}}- : A {{domxref("FederatedCredentialInit")}} object containing requirements for creating a federated identify provider credential.
password{{optional_inline}}- : A {{domxref("PasswordCredentialInit")}} object containing requirements for creating a password credential.
publicKey{{optional_inline}}- : A {{domxref("PublicKeyCredentialCreationOptions")}} object containing requirements for creating a public key credential. Causes the
create()call to request that the user agent creates new credentials via an authenticator — either for registering a new account or for associating a new asymmetric key pair with an existing account.
توجه: Usage of create() with the publicKey parameter may be blocked by a {{HTTPHeader("Permissions-Policy/publickey-credentials-create","publickey-credentials-create")}} Permissions Policy set on your server.
Return value
A {{jsxref("Promise")}} that resolves with one of the following:
- A {{domxref("FederatedCredential")}}, if the credential type was
federated. - A {{domxref("PasswordCredential")}}, if the credential type was
password. - A {{domxref("PublicKeyCredential")}}, if the credential type was
publicKey.
If no credential object can be created, the promise resolves with null.
Exceptions
- {{jsxref("TypeError")}}
- : In the case of a {{domxref("PasswordCredential")}} creation request,
id,origin, orpasswordwere not provided (empty). NotAllowedError{{domxref("DOMException")}}- : Possible causes include:
- Usage is blocked by a {{HTTPHeader("Permissions-Policy/publickey-credentials-create","publickey-credentials-create")}} Permissions Policy.
- The function is called cross-origin but the iframe's [
allow](/en-US/docs/Web/HTML/Reference/Elements/iframe#allow) attribute does not set an appropriate {{HTTPHeader("Permissions-Policy/publickey-credentials-create","publickey-credentials-create")}} policy. - The function is called cross-origin and the
<iframe>does not have {{glossary("transient activation")}}. - The function tries to create a discoverable credential ([
residentKey](/en-US/docs/Web/API/PublicKeyCredentialCreationOptions#residentkey) is set torequiredin thecreate()call's {{domxref("PublicKeyCredentialCreationOptions")}} option), but the user does not have an authenticator that supports discoverable credentials. - The
mediationoption is set to"conditional", but the conditions were not met. See Conditional create for more details. AbortError{{domxref("DOMException")}}- : The operation was aborted.
Examples
Creating a password credential
This example creates a password credential from a {{domxref("PasswordCredentialInit")}} object.
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
});Creating a federated credential
This example creates a federated credential from a {{domxref("FederatedCredentialInit")}} object.
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);
});Creating a public key credential
This example creates a public key credential from a {{domxref("PublicKeyCredentialCreationOptions")}} object.
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 });The create() call, if successful, returns a promise that resolves with a {{domxref("PublicKeyCredential")}} object instance, representing a public key credential that can later be used to authenticate a user via a WebAuthn {{domxref("CredentialsContainer.get()", "get()")}} call. Its {{domxref("PublicKeyCredential.response")}} property contains an {{domxref("AuthenticatorAttestationResponse")}} object providing access to several useful pieces of information including the authenticator data, public key, transport mechanisms, and more.
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();
});Some of this data will need to be stored on the server for future authentication operations against this credential — for example the public key, the algorithm used, and the permissible transports.
توجه: See Creating a key pair and registering a user for more information about how the overall flow works.
Creating a public key credential using conditional create
This example uses conditional create, which is specified by setting the mediation option to conditional. It attempts to create a new passkey without requiring any user interaction, when the conditions defined for conditional create are met.
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
}
}Note that this example:
- Only attempts conditional create if the user does not already have a passkey
- Aborts any outstanding attempts to get or create a public key credential before attempting conditional create.
- Catches and ignores any errors that are thrown if, for example, the conditions were not met.
Specifications
{{Specifications}}
Browser compatibility
{{Compat}}