docs: document WebAuthn conditional create - #44643
Conversation
github-actions
Bot
added
Content:WebAPI
|
@wbamberg I believe you would be the right person to review that. Thanks! |
| - `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 an `AbortError` {{domxref("DOMException")}}. | ||
| - `mediation` {{optional_inline}} | ||
| - : A string indicating how user mediation should be handled for the credential creation request. For public key credentials, a value of `"conditional"` requests [automatic passkey creation](#creating_a_passkey_conditionally) when the user agent and passkey provider support it, and the user has recently signed in with a saved password. |
There was a problem hiding this comment.
We document enumerations by listing all the valid values in a nested <dl>, see for example the version of this option under get(): https://developer.mozilla.org/en-US/docs/Web/API/CredentialsContainer/get#mediation.
The IDL suggests that all four values can be passed here, but I don't know whether they are actually supported in create().
| > [!NOTE] | ||
| > See [Creating a key pair and registering a user](/en-US/docs/Web/API/Web_Authentication_API#creating_a_key_pair_and_registering_a_user) for more information about how the overall flow works. | ||
|
|
||
| ### Creating a passkey conditionally |
There was a problem hiding this comment.
I think examples should just be examples: that is, they should illustrate features that are described elsewhere. That is, you should be able to learn all about a feature just by reading its description. So I don;t really think examples should come with a lot of explanatory text about the behavior of the feature being illustrated - that should live elsewhere.
So:
- EITHER this page should have an H2 "description", which could integrate some of the stuff from the start of the page (especially, about how you can create various different types of credential) and then we could put this descriptive content in an H3 under there
- OR, since you already describe the feature in the WebAuthn overview page, we could just link to that description.
I think the first option is better, but more work of course.
|
|
||
| ### Creating a passkey conditionally | ||
|
|
||
| _Automatic passkey creation_, also known as _conditional create_, lets a relying party (RP) request passkey creation without requiring the user to explicitly choose a "create a passkey" control. |
There was a problem hiding this comment.
We don't use the RP terminology in the rest of the page so it's weird to introduce it here. We could just say "website" IMO.
| } | ||
| ``` | ||
|
|
||
| A conditional creation request can fail when the user agent or selected passkey provider cannot satisfy the request — for example, if the user did not recently sign in using a saved password, or if a matching passkey already exists. |
There was a problem hiding this comment.
| A conditional creation request can fail when the user agent or selected passkey provider cannot satisfy the request — for example, if the user did not recently sign in using a saved password, or if a matching passkey already exists. | |
| A conditional creation request will throw an `NotAllowedError` exception when the conditions are not met — for example, if the user did not recently sign in using a saved password, or if a matching passkey already exists. |
(note, this also means we ought to add this case to the list under https://pr44643.review.mdn.allizom.net/en-US/docs/Web/API/CredentialsContainer/create#notallowederror )
| A web application could use this to display a fingerprint icon if the capability is supported, or a password input if it is not. | ||
| If biometric login is required, then it could instead provide notification that the site cannot authenticate using this browser or device. | ||
| Similarly, `conditionalGet` indicates that the client supports conditional mediation when signing in a user, which means the browser can provide auto-filled discoverable credentials in a login form (for example an autocompleting text field or a drop-down list), along with a sign-in button. | ||
| The `conditionalCreate` capability indicates support for conditional creation, which means a website can request passkey creation after a successful password sign-in by calling {{domxref("CredentialsContainer.create()")}} with `mediation: "conditional"`. |
There was a problem hiding this comment.
I don't think you need this. The list here is not intended to be exhaustive, it's just giving a couple of examples.
|
|
||
| - `"conditionalCreate"` | ||
| - : The client is capable of creating [discoverable credentials](/en-US/docs/Web/API/Web_Authentication_API#discoverable_and_non-discoverable_credentials). | ||
| - : The client is capable of [automatic passkey creation](/en-US/docs/Web/API/Web_Authentication_API#automatic_passkey_creation) using {{domxref("CredentialsContainer.create()")}} with `mediation: "conditional"`. |
There was a problem hiding this comment.
| - : The client is capable of [automatic passkey creation](/en-US/docs/Web/API/Web_Authentication_API#automatic_passkey_creation) using {{domxref("CredentialsContainer.create()")}} with `mediation: "conditional"`. | |
| - : The client is capable of [automatic passkey creation](/en-US/docs/Web/API/Web_Authentication_API#automatic_passkey_creation). |
|
|
||
| ### Automatic passkey creation | ||
|
|
||
| Automatic passkey creation, also known as _conditional create_, lets an RP ask the browser to create a passkey after the user has already signed in with a password. |
There was a problem hiding this comment.
This is a curious statement: you don't need conditional create to "ask the browser to create a passkey". The point of course is to create a passkeys without asking the user first.
| Automatic passkey creation, also known as _conditional create_, lets an RP ask the browser to create a passkey after the user has already signed in with a password. | |
| Automatic passkey creation, also known as _conditional create_, lets an RP ask the browser to create a passkey automatically, without asking the user, when certain conditions are met: specifically, when the user has previously agreed to create a credential and has recently signed in. |
...or something like that.
There was a problem hiding this comment.
But tbh I'm not exactly sure what the conditions are here. In this: https://developer.mozilla.org/en-US/docs/Web/Security/Authentication/Passkeys#conditional_create we say:
If the user has just signed in with a password, using a password manager that also supports passkeys (that is, a credentials manager that can also function as an authenticator), then the browser will ask that credentials manager to create a new passkey for the user, without asking the user.
...that is, the user must have signed in using a password stored in that credentials manager, and this kind of makes sense, as we also say:
The theory here is that if the user is relying on a credentials manager for sign-in already, then they implicitly trust it to look after their sign-in credentials in general, so they can trust it to create a new form of credential for them.
So that implies that if the user signs in with a password that isn't stored in a password manager, then the condition is not met.
The spec says:
a user has previously consented to credential creation and the user agent knows it recently mediated an authentication
...which is a bit hard to understand, but "consented to credential creation" presumably implies that the password was stored in a password manager, since that's what create() means with a password credential.
| If it is supported, call {{domxref("CredentialsContainer.create()")}} with: | ||
|
|
||
| - The usual [`publicKey`](/en-US/docs/Web/API/CredentialsContainer/create#publickey) creation options from the RP server. | ||
| - [`mediation: "conditional"`](/en-US/docs/Web/API/CredentialsContainer/create#mediation). |
There was a problem hiding this comment.
| - [`mediation: "conditional"`](/en-US/docs/Web/API/CredentialsContainer/create#mediation). | |
| The `mediation` option set to [`"conditional"`](/en-US/docs/Web/API/CredentialsContainer/create#mediation). |
| ``` | ||
|
|
||
| Call this flow soon after a successful password-based sign-in, while the user is still signed in. | ||
| Conditional creation may fail if the required conditions are not met, so handle failures without showing errors to the user. |
There was a problem hiding this comment.
| Conditional creation may fail if the required conditions are not met, so handle failures without showing errors to the user. | |
| Conditional creation will fail if the required conditions are not met, so handle failures without showing errors to the user. |
4 participants
Description
Adds documentation for WebAuthn conditional create / automatic passkey creation.
Changes:
mediationoption onCredentialsContainer.create()and explainsmediation: "conditional"for public key credential creation.create()example showing feature detection withPublicKeyCredential.getClientCapabilities()and a conditional passkey creation request.conditionalCreateclient capability refers to automatic passkey creation, not just creating discoverable credentials.Motivation
Conditional create lets sites request passkey creation after a successful password sign-in, helping users adopt passkeys without needing to explicitly find and click a separate “create passkey” control.
Fixes #42516.
Additional details
Validated with:
git diff --checkmarkdownlint-cli2on the changed files using Node 22.23.1prettier -con the changed files using Node 22.23.1