--- title: WebAuthn Authentication node description: Lets users on supported clients use a registered FIDO device during authentication. component: auth-node-ref version: 7.3 page_id: auth-node-ref::auth-node-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 section_ids: 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, this node requires the username in the shared state. Implement a [Username Collector node](am-only/auth-node-username-collector.html) (standalone AM) or [Platform Username node](auth-node-platform-username.html) (Ping Identity Platform deployment) before this node in the journey. ## Outcomes * `Unsupported` * `No Device Registered` * `Success` * `Failure` * `Client Error` * `Recovery Code` (configurable) If the user's client does not support web authentication, evaluation continue 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). If the user does not have a registered device, evaluation continues along the `No Device Registered` outcome path. 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. 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. | 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](auth-node-recovery-code-collector-decision.html). 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. ## 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](auth-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.Find more information in [Configure usernameless authentication with ForgeRock Go](https://docs.pingidentity.com/pingam/7.3/authentication-guide/authn-mfa-webauthn.html#webauthn-usernameless-with-forgerock-go). | | Return challenge as JavaScript | Specifies that the node returns its challenge as a fully encapsulated client-side JavaScript that interacts directly with the WebAuthn API, and auto-submits the response back.If disabled, the node returns the challenge and associated data in a metadata callback. A custom UI, for example an application using the [Ping SDKs](https://docs.pingidentity.com/sdks/latest/index.html), uses the information from the callback to interact with the WebAuthn API on AM's behalf. | ## Example This example shows one possible implementation of the flow for authenticating with WebAuthn devices: ![trees-node-webauthn-auth-example](_images/trees-node-webauthn-auth-example.png)Figure 1. Access Management![trees-node-webauthn-auth-example](_images/trees-node-webauthn-auth-example-platform.png)Figure 2. Ping Identity Platform 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](auth-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.png)Figure 3. Access Management![trees-node-webauthn-waiting](_images/trees-node-webauthn-waiting-platform.png)Figure 4. Ping Identity Platform 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](auth-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` outcome, including a timeout, or to the `Client Error` outcome, resulting in an authentication failure.