Skip to main content

Operations

This document provides an overview of two main operations performed through the WebAuthn API: registering a new passkey (registration) and signing in (authentication).

Registering a passkey​

Registration requests are invoked using the navigator.credentials.create() method (MDN).

  1. Client-Side Server Request: The application (usually a JavaScript application running in a web browser) initiates the registration process by making a request to the server to create a new FIDO2 credential.

  2. Server-Side Preparation: The server prepares for the registration process by generating an options object, usually with the help of a code library (e.g. fido2-net-lib). This object includes the following parameters:

    • attestation: The attestation statement format to use during the registration process. This can be set to none if the server does not require attestation.
    • authenticatorSelection: An object that specifies the authenticator attachment modality and the user verification requirement.
    • challenge: A random value generated by the server that will be used to verify the authenticity of the subsequent response from the client.
    • excludeCredentials: A list of existing credentials that the server should exclude from the registration process. This is useful for preventing duplicate registrations, by aborting the registration if the authenticator finds an existing credential that matches one of the credentials in this list.
    • pubKeyCredParams: A list of public key parameters that the server is willing to accept for the new credential. This includes the cryptographic algorithm and the key type.
    • rp: An object that contains information about the Relying Party (RP). This includes the RPs name, ID, and icon.
    • timeout: The time, in milliseconds, that the client is willing to wait for the authenticator to complete the registration process.
    • user: An object that contains information about the user. This includes the user's ID, name, display name, and icon.
    • extensions: An object that contains any additional parameters that the server wants to include in the registration process. An example of this is the prf extension, which enables the credential to be used for data encryption.

  3. Client-Side WebAuthn Request: The application receives the options object from the server and passes it to navigator.credentials.create().

  4. Client-Side Credential Creation Request: The WebAuthn Client receives the options object, validates it, searches for connected authenticators, and then sends the options object to all connected authenticators to create a new FIDO2 credential.

  5. User Interaction: All connected authenticators will indicate that they have received the request and are ready to create a new credential (e.g. using a blinking LED). The user will then need to perform an action to confirm the creation of the new credential (e.g. by pressing a button on the authenticator).

  6. Authenticator Response: Once the user confirms the creation of the new credential, the authenticator generates a new public-private key pair and creates a new credential object. This object includes the credentialId, public key, a signature, the type of authenticator used, the attestation statement, and other relevant information.

  7. Client-Side Response: Once the credential is created, the client sends a request back to the server. This request includes the newly-created credential and all the other relevant information received from the authenticator.

  8. Server-Side Validation: The server receives the request from the client and performs several checks to validate the authenticity and integrity of the received data. This includes verifying the challenge, verifying the signature of the credential, checking the attestation statement, etc. This is usually performed by a code library.

  9. Server-Side Credential Storage: If the validation is successful, the server stores the credential securely in its database, associating it with the user's account or any other relevant information.

  10. Registration Completion: Finally, the server responds to the client, indicating that the registration process was successful. At this point, the user has successfully registered a FIDO2 credential that can be used for future authentication.

The private key generated during the credential creation process is always protected by the authenticator/passkey provider, ensuring that the user's credentials are protected even if the server is compromised.

Authenticating with a passkey​

Authentication requests are invoked using the navigator.credentials.get() method (MDN).

  1. Client-Side Request: The application initiates the registration process by making a request to the server. This request is typically triggered by a user action, such as:

    • Clicking on a "Log in with Passkey" button
    • Entering a username and clicking on a "Log in" button

  2. Server-Side Preparation: The server prepares for the authentication process by generating an options object containing a challenge, similar to the registration process.

    a. If the user's identity is not known, the server will simply send a challenge and the rpId. b. If the user's identity is known, the server will also send along all of the user's credentialId that were stored during the registration process.

  3. Client-Side WebAuthn Request: The application receives the options object from the server and passes it to navigator.credentials.get().

  4. Client-Side Credential Assertion Request: The WebAuthn Client receives the options object, validates it, searches for connected authenticators, and then sends the options object to all connected authenticators to generate an assertion.

  5. User Interaction: All connected authenticators will indicate that they have received the request and are ready to assert a credential (e.g. using a blinking LED). The user will then need to perform an action to confirm the assertion of the new credential (e.g. by pressing a button on the authenticator).

  6. Authenticator Response: Once the user confirms the assertion, the authenticator generates a new assertion object. This object includes a signature for the challenge and the credentialId for the credential that was used to generate the challenge. This might also include a userHandle so that the server can identify the user. The value of the userHandle is the value of the user.id field that was used during the registration process.

  7. Client-Side Response: Once the credential is asserted, the client sends a request back to the server, containing the assertion response.

  8. Server-Side Validation: The server receives the request from the client and performs several checks to validate the authenticity and integrity of the received data. This includes verifying the signature of the credential against the public key associated with the returned credentialId. This is usually performed by a code library.

  9. Authentication Completion: Finally, the server responds to the client, indicating that the authentication process was successful. At this point, the user has successfully logged in using a FIDO2 Credential.

User presence​

User presence is a measure of the user's physical presence during the registration or authentication. It is determined by the authenticator, which can use a variety of methods to detect user presence, such as a button press.

The WebAuthn API always requires user presence and does not provides a way to configure this requirement. This is why you are always required to perform an action on your authenticator when you use your passkeys on the web. CTAP2 does provide a way to configure the user presence requirement, but this is not exposed through the WebAuthn API.

User verification​

User verification is a process that ensures that the user is not only present but is also verified by the authenticator. This can be done using a variety of methods, such as a PIN, biometric verification, or a password. The WebAuthn API provides a way to specify if the RP prefers (or requires) user verification when a new credential is created or when an existing credential is used to authenticate. This is done using the authenticatorSelection parameter in the options object.

It is worth noting that the WebAuthn API does not provide a way to forbid user verification, which means that in some cases the authenticator will always verify the user, even if the RP does not require it. An example of this is the YubiKey Bio series, which only has a fingerprint reader as a means of interaction, and therefore always verifies the user.