--- title: WebAuthn Authentication node description: Lets users on supported clients use a registered FIDO device during authentication. component: auth-node-ref version: 7.4 page_id: auth-node-ref::webauthn-auth canonical_url: https://docs.pingidentity.com/auth-node-ref/latest/webauthn-authentication.html llms_txt: https://docs.pingidentity.com/auth-node-ref/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["Nodes & Trees", "Journeys", "Authentication"] page_aliases: ["auth-node-webauthn-auth.adoc"] section_ids: compatibility: Compatibility outcomes: Outcomes properties: Properties example: Example --- # WebAuthn Authentication node Lets users on supported clients use a registered FIDO device during authentication. To determine whether the user has a registered device, the node reads the `username` from the shared state. Implement a [Username Collector node](am-only/username-collector.html) (standalone AM) or [Platform Username node](platform-username.html) (Ping Identity Platform deployment) earlier in the journey. ## Compatibility | Product | Compatible? | | ------------------------------------------ | --------------------- | | PingOne Advanced Identity Cloud | [icon: check, set=fa] | | ForgeRock Access Management (self-managed) | [icon: check, set=fa] | | Ping Identity Platform (self-managed) | [icon: check, set=fa] | ## Outcomes * `Unsupported` If the user's client doesn't support web authentication, evaluation continues along the `Unsupported` outcome path. For example, clients connected over the HTTP protocol rather than HTTPS do not support WebAuthn; however, HTTPS may not be required when testing locally, on `http://localhost`. For more information, refer to [Is origin potentially trustworthy?](https://w3c.github.io/webappsec-secure-contexts/#potentially-trustworthy-origin). * `No Device Registered` If the user does not have a registered device, evaluation continues along the `No Device Registered` outcome path. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | * Username enumeration risk When WebAuthn is the only authentication method, routing the `No Device Registered` outcome to a visually distinct path, such as password login or device registration, allows attackers to identify valid usernames. When the node processes the request, it performs a username-to-device lookup *before* issuing any WebAuthn challenge or triggering any browser interaction. This means that a difference in response reveals whether a passkey exists for the user. This risk is noted in [§14.6.2 of the W3C WebAuthn Level 2 specification](https://www.w3.org/TR/webauthn-2/#sctn-username-enumeration). * Mitigation Design your journey to route `No Device Registered` to the same generic failure handling as the `Failure` outcome. This ensures the UI, response, and timing of the journey all remain indistinguishable to an attacker. | * `Success` If the user successfully authenticates with a device of the type determined by the User verification requirement property, evaluation continues along the `Success` outcome path. * `Failure` If AM encounters an issue when attempting to authenticate using the device, evaluation continues along the `Failure` outcome path. For example, AM could not verify that the response from the authenticator was appropriate for the specific instance of the authentication ceremony. * `Client Error` If the user's client encounters an issue when attempting to authenticate using the device, for example, if the timeout was reached, evaluation continues along the `Client Error` outcome path. This outcome is used whenever the client throws a `DOMException`, as required by the [Web Authentication: An API for accessing Public Key Credentials Level 1](https://www.w3.org/TR/webauthn/) specification. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If a client error occurs, the error type and description are added to a property named `WebAuthenticationDOMException` in the shared state. This property can be read by other nodes later, if required. | * `Recovery Code` (configurable) If Allow recovery code is enabled, AM provides the user the option to enter a recovery code rather than authenticate using a device. Evaluation continues along the `Recovery Code` outcome path if the users chooses to enter a recovery code. To accept and verify the recovery code, ensure the outcome path leads to a [Recovery Code Collector Decision node](recovery-code-collector-decision.html). ## Properties | Property | Usage | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Relying party identifier | Specifies the domain used as the [relying party identifier](https://www.w3.org/TR/webauthn/#relying-party-identifier) during web authentication. If not specified, AM uses the domain name of the instance, for example, `am.example.com`.Specify an alternative domain if your AM instances are behind a load balancer, for example. | | Origin domains | Specifies a list of fully qualified URLs to accept as the origin of incoming requests.If left empty, AM accepts any incoming domain. | | User verification requirement | Specifies the required level of [user verification](https://www.w3.org/TR/webauthn/#user-verification).The available options are:- `REQUIRED` The authenticator used must verify the identity of the user, for example, by using biometrics. Authenticators that do not verify the identity of the user should not be activated for authentication. - `PREFERRED` Use of an authenticator that verifies the identity of the user is preferred, but if none are available any authenticator is accepted. - `DISCOURAGED` Use of an authenticator that verifies the identity of the user is not required. Authenticators that do not verify the identity of the user should be preferred. | | Allow recovery codes | Specify whether to allow the user to enter one of their recovery codes instead of performing an authentication gesture.Enabling this options adds a `Recovery Code` outcome path to the node. This outcome path should lead to a [Recovery Code Collector Decision node](recovery-code-collector-decision.html) to collect and verify the recovery code. | | Timeout | Specify the number of seconds to wait for a response from an authenticator.If the specified time is reached, evaluation continues along the `Client error` outcome path, and a relevant message is stored in the `WebAuthenticationDOMException` property of the shared state. | | Username from device | Specifies whether AM requests that the device provides the username.When enabled, if the device is unable to store or provide usernames, the node fails and evaluation continues along the `Failure` path.For information on using this property for usernameless authentication with ForgeRock Go, refer to [Configure usernameless authentication with ForgeRock Go](https://docs.pingidentity.com/pingam/7.4/am-authentication/authn-mfa-webauthn.html#webauthn-usernameless-with-forgerock-go). | | Return challenge as JavaScript | Choose how the node should return its challenge for consumption by your front-end user interface:- Ping SDK client apps: If your authentication user interface is built with the Ping SDKs, you should either deselect this option or use SDK for JavaScript 4.9.0 or later. When not enabled, the node returns the challenge and associated data in a metadata callback. Ping SDK client apps that might not be able to execute JavaScript use the information from the callback to interact with WebAuthn APIs on AM's behalf. - Access Management User UI: You should only enable this option if you are using the Access Management User UI to authenticate users. Enabling this option causes the node to return its challenge as a fully encapsulated client-side JavaScript that interacts directly with the WebAuthn API. | ## Example This example shows one possible implementation of the flow for authenticating with WebAuthn devices: ![WebAuthn Authentication node example](_images/journey-webauthn-auth.png) After verifying the users credentials against the configured data store, evaluation continues to the WebAuthn Authentication node. If the user's client does not support WebAuthn, authentication fails and the user does not get a session. A more user-friendly approach would be to set a success URL to redirect the user to a page explaining the benefits of multi-factor authentication, and then proceeding to the `Success` node. If there are no registered WebAuthn devices present in the user's profile, the failure URL is set, pointing to a flow that lets the user register a device. This stage could also be an [Inner Tree Evaluator node](inner-tree-evaluator.html). If the user's client does support WebAuthn, and the connection is secured with TLS, the user is prompted to complete an [authorization gesture](https://www.w3.org/TR/webauthn/#authorization-gesture), for example, scanning a fingerprint, or entering a PIN: ![trees-node-webauthn-waiting](_images/trees-node-webauthn-waiting-platform.png) The user's browser may present a consent pop-up to allow access to the authenticators available on the client. When consent has been granted, the browser activates the relevant authenticators, ready for authentication. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------ | | | The relying party details configured in the node are often included in the consent message to help the user verify the entity requesting access. | The authenticators the client activates for authentication depends on the value of the properties in the node. For example, if the User verification requirement property is set to `REQUIRED`, the client **SHOULD** only activate authenticators which verify the identity of the user. For extra protection, AM **WILL** verify the response from an authenticator matches the criteria configured for the node, and will reject—​with the `Failure` outcome—​an authentication attempt by an inappropriate authenticator type. When the user completes an [authorization gesture](https://www.w3.org/TR/webauthn/#authorization-gesture), for example, by scanning a fingerprint or entering a PIN, evaluation continues along the `Success` outcome path. In this example, their authentication level is increased by ten to signify the stronger authentication that has occurred, and the user is taken to their profile page. If the user clicks the `Use Recovery Code` button, evaluation continues to the [Recovery Code Collector Decision node](recovery-code-collector-decision.html), ready to accept the recovery code. If verified, the user is taken to their profile page. Any problems encountered during authentication lead to the `Failure`, `Client Error`, or `Sign Count Mismatch` outcomes, resulting in an authentication failure.