--- title: WebAuthn Authentication node description: Configure the WebAuthn Authentication node to let users authenticate with a registered FIDO device, including passkeys and hardware security keys, in PingAM. component: platform version: 7.5 page_id: platform:auth-node-ref:webauthn-authentication canonical_url: https://docs.pingidentity.com/platform/7.5/auth-node-ref/webauthn-authentication.html llms_txt: https://docs.pingidentity.com/platform/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", "webauthn-auth.adoc"] section_ids: availability: Availability inputs: Inputs prerequisites: Prerequisites configuration: Configuration outcomes: Outcomes outputs: Outputs example: Example --- # WebAuthn Authentication node The WebAuthn Authentication node lets users on supported clients authenticate using a registered [FIDO](https://fidoalliance.org/how-fido-works/) device. ## Availability | Product | Available? | | ------------------------------------- | ---------- | | PingOne Advanced Identity Cloud | Yes | | PingAM (self-managed) | Yes | | Ping Identity Platform (self-managed) | Yes | ## Inputs The node reads the `username` from the shared state. Implement the following node before this node in the journey: * [Username Collector node](am-only/username-collector.html) (standalone AM) * [Platform Username node](platform-username.html) (Ping Identity Platform deployment) ## Prerequisites For successful authentication, this node depends on: * A client that supports web authentication * A registered FIDO device ## Configuration | Property | Usage | | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Relying party identifier | The domain used as the [relying party identifier](https://www.w3.org/TR/webauthn/#relying-party-identifier) during web authentication. This is the domain against which to register the device.If you leave this field blank, it defaults to the domain name of the AM instance, for example, `am.example.com`. Specify an alternative domain if your AM instances are behind a load balancer, for example. | | Origin domains | A list of fully qualified URLs to accept as the origin of the incoming request.If this field is empty, the accepted origin is the incoming request origin. | | User verification requirement | The required [user verification](https://www.w3.org/TR/webauthn/#user-verification) level.The available options are:- `REQUIRED` The authenticator used must verify the user's identity, for example, by using biometrics. Authenticators that don't verify the user's identity are filtered out and can't be selected by the user. - `PREFERRED` If multiple authenticators are presented, Ping Identity Platform prefers those that verify the user's identity. If none are available, Ping Identity Platform accepts any authenticator. - `DISCOURAGED` Ping Identity Platform doesn't require an authenticator that verifies the user's identity. Authenticators that don't verify the user's identity are preferred. | | Allow recovery codes | If you select this option, Ping Identity Platform lets the user enter a recovery code instead of performing an authentication gesture.Enabling this options adds a `Recovery Code` outcome path to the node. The outcome path should lead to a [Recovery Code Collector Decision node](recovery-code-collector-decision.html) to collect and verify the recovery code. | | Timeout | The number of seconds to wait for a valid WebAuthn authenticator to be registered before failing.If the specified timeout is reached, evaluation continues along the `Client error` outcome path. Ping Identity Platform stores a message in the `WebAuthenticationDOMException` property of the shared state. | | Username from device | Specifies whether Ping Identity Platform should get the username from the device.If you enable this option and the device is unable to store or provide usernames, the node fails and evaluation continues along the `Failure` path.You can find information on using this property in [Configure usernameless authentication](https://docs.pingidentity.com/pingam/7.5/am-authentication/authn-mfa-webauthn.html#webauthn-usernameless). | | 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 Ping Identity Platform's behalf. - PingAM User UI: You should only enable this option if you are using the PingAM 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. | ## 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 don't 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 doesn't 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 the node encounters an issue when attempting to authenticate the user with the device, evaluation continues along the `Failure` outcome path; for example, if the node can't verify that the response from the authenticator was appropriate for the specific instance of the authentication journey. * `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. The journey takes this path 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. * `Recovery Code` If Allow recovery code is enabled, the node gives the user an option to enter a recovery code rather than authenticate using a device. If the user enters a recovery code, evaluation continues along the `Recovery Code` outcome path. This outcome path must lead to a [Recovery Code Collector Decision node](recovery-code-collector-decision.html) to let Ping Identity Platform accept and verify the recovery code. ## Outputs If a client error occurs, the node adds the error type and description to a property named `WebAuthenticationDOMException` in the shared state. Other nodes can read this property later in the journey, if required. | | | | - | ---------------------------------------------------------------------------------------------------- | | | The contents of the transient state for this node aren't public. Don't rely on them in your scripts. | ## Example This example shows one possible implementation of the flow for authenticating with WebAuthn devices: ![Example WebAuthn authentication journey](_images/journey-webauthn-auth.png) * After verifying the user's credentials against the configured data store, evaluation continues to the WebAuthn Authentication node. * If the user's client doesn't support WebAuthn, authentication fails and the user doesn't 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 the user profile has no registered WebAuthn devices, the journey continues to the generic failure outcome. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This prevents the [risk of username enumeration](#username-enumeration-risk) by ensuring that a response for a missing device is indistinguishable from a failed authentication. | * If the user's client supports 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 depend 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 that verify the identity of the user. For extra protection, Ping Identity Platform **WILL** verify that the response from an authenticator matches the criteria configured for the node, and will reject an authentication attempt by an inappropriate authenticator type by routing it to the `Failure` outcome. * 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.