--- title: WebAuthn Authentication node description: The WebAuthn Authentication node lets users on supported clients authenticate using a registered FIDO device. component: auth-node-ref version: latest page_id: auth-node-ref::webauthn-authentication canonical_url: https://docs.pingidentity.com/auth-node-ref/latest/webauthn-authentication.html keywords: ["Nodes & Trees", "Journeys", "Authentication"] page_aliases: ["auth-node-webauthn-auth.adoc"] superseded_by: https://docs.pingidentity.com/auth-node-ref/latest/webauthn-authentication.html section_ids: examples: Examples example_1_webauthn_authentication_journey: "Example 1: WebAuthn authentication journey" example_2_webauthn_authentication_with_conditional_ui: "Example 2: WebAuthn authentication with conditional UI" availability: Availability inputs: Inputs dependencies: Dependencies configuration: Configuration outputs: Outputs callbacks: Callbacks outcomes: Outcomes changelog: Changelog --- # WebAuthn Authentication node The WebAuthn Authentication node lets users on supported clients authenticate using a registered [FIDO](https://fidoalliance.org/how-fido-works/) device. > **Collapse: What are the differences between WebAuthn and device binding/signing?** > > There are many similarities between WebAuthn and device binding and JWS verification. We provide authentication nodes to implement both technologies in your journeys. > > Both can be used for usernameless and passwordless authentication, they both use public key cryptography, and both can be used as part of a multi-factor authentication journey. > > One major difference is that with device binding, the private key never leaves the device. > > With WebAuthn, there is a possibility that the private key is synchronized across client devices because of Passkey support, which may be undesirable for your organization. > > For details of the differences, refer to the following table: > > **Comparison of WebAuthn and Device Binding/JWS Verification** > > | Feature | WebAuthn / FIDO | Device Binding / JWS Verifier | Details | > | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | Industry-standards based | ✅ | ❌ | You can refer to the [WebAuthn W3C specification](https://www.w3.org/TR/webauthn-2/).Device binding and JWS verification are proprietary implementations. | > | Public key cryptography | ✅ | ✅ | Both methods use [Public key cryptography](https://en.wikipedia.org/wiki/Public-key_cryptography). | > | Usernameless support | ✅ | ✅ | After registration, the username can be stored in the device and obtained during authentication without the user having to enter their credentials. | > | Keys are bound to the device | ❌ | ✅ | With WebAuthn, if Passkeys are used, they can be shared across devices.With device binding, the private keys do not leave the device. | > | Sign custom data | ❌ | ✅ | With device binding, you can:- Customize the challenge that the device must sign. For example, you could include details of a transaction, such as the amount in dollars. > > - Add custom claims to the payload when signing a challenge. This gives additional context that the server can make use of by using a scripted node. > > Refer to [Add custom claims when signing](https://docs.pingidentity.com/sdks/latest/sdks/use-cases/how-to-bind-devices.html#add_custom_claims_when_signing). | > | Format of signed data | [WebAuthn authenticator data](https://www.w3.org/TR/webauthn/#authenticator-data) | [JSON Web Signature (JWS)](https://openid.net/specs/draft-jones-json-web-signature-04.html) | | > | Integration | ❌ | ✅ | With device binding, after verification, the signed JWT is available in:- Audit Logs > > - Transient node stateThis enables the data within to be used for integration into your processes and business logic. | > | Platform support | ✅ Android✅ iOS✅ Web browsers | ✅ Android✅ iOS❌ Web browsers | As it is challenging to store secure data in a browser as a client app, device binding is not supported in web browsers. | > | Authenticator support | Determined by the platform.Configuration limited to:- Biometric with Fallback to Device Pin | Determined by the authentication node.Full configuration options:- Biometric Authentication > > - Biometric with Fallback to Device Pin > > - Application Pin > > - Silent | With device binding, you can specify what authentication action the user must perform to get access to the private keys.This provides greater flexibility in your security implementation and can reduce authentication friction for your users. | > | Key storage | Web browsers and iOS synchronize to the cloud.Android has the option to synchronize to the cloud. | * Android > > KeyStore > > * iOS > > Secure enclave: hardware-backed and not synchronized to the cloud. | Both technologies store the private keys securely on the client.WebAuthn supports synchronizing the private keys to the cloud for use on other devices.This can reduce authentication friction for your users but may also increase the risk of a breach. | > | Managing device keys | Managed by the device OS.Apps cannot delete *local* client keys programmatically and do not have a reference to the *remote* server key for deletion. | Managed by the Ping SDKs.Provides an interface to delete local client and remote server keys. | The ability to programmatically delete both client and server keys can greatly simplify the process of registering a new device if an old device is lost or stolen. | > | Passkey support | ✅ | ❌ | WebAuthn supports synchronizing the private keys to the cloud for use on other devices.Device binding keeps the private key locked in the device. | > | App integrity verification | - Android > > Requires an `assetlinks.json` file. > > - iOS > > Requires `apple-app-site-association` file. | Not provided by the device binding or verification nodes.It can be added as part of the journey by using app integrity nodes. | App integrity verification helps ensure your users are only using a supported app rather than a third-party or potentially malicious version. | > | Key attestation | * Android > > SafetyNet > > * iOS > > None | - Android > > Uses [hardware-backed key pairs with Key Attestation](https://developer.android.com/privacy-and-security/security-key-attestation). > > - iOS > > It can be added as part of the journey by using app integrity nodes to support key attestation. | Key attestation verifies that the private key is valid and correct, is not forged, and was not created in an insecure manner. | > | Complexity | Medium | Low | WebAuthn requires a bit more configuration, for example, creating and uploading the `assetlinks.json` and `apple-app-site-association` files.Device binding only requires the journey and the SDK built into your app. | | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | To authenticate using WebAuthn on an Android or iOS device without an external keystore, screen lock *must* be enabled. Find more information in the respective device documentation for [Android](https://support.google.com/accounts/answer/13548313?hl=en) and [iOS](https://support.apple.com/en-gb/102195). | ## Examples ### Example 1: WebAuthn authentication journey 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/webauthn-waiting.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, Advanced Identity Cloud **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. ### Example 2: WebAuthn authentication with conditional UI AM only *(tooltip: Currently available only in AM 8.1)* The following example journey lets the user authenticate using social authentication, a username and password, or a passkey: ![Journey with WebAuthn conditional UI and social authentication](_images/webauthn-conditional-ui-example-journey.png) The v2.0 [Page node](page.html) provides the user with different authentication options on the same page. The Page node contains the following nodes: * [Platform Username node](platform-username.html). This node uses the following configuration to provide users with relevant autofill suggestions, including passkeys if they're available: * Autocomplete Values `username`\ `webauthn` The autocomplete values must be in this order. * [Platform Password node](platform-password.html) * [Select Identity Provider node](select-identity-provider.html). This node is configured to include local authentication. * [WebAuthn Authentication node](webauthn-authentication.html). This node is v2.0 and uses the following configuration to provide the WebAuthn conditional UI and Sign in with passkey button: * Username from device `Enabled` * Mediation `CONDITIONAL` * Authentication Button `Enabled` The standalone nodes must be added after the non-standalone nodes. This Page node configuration presents a Sign in page to the user similar to the following: ![Example Sign in page with passkey and social authentication options](_images/webauthn-conditional-ui-signin-page.png) * If the user chooses Google in this example, the [Social Provider Handler node](social-provider-handler.html) routes the user to Google to authenticate. If authentication is successful, the user follows the `Account exists` path. Otherwise, they can try a different authentication method. * If the user clicks in the User Name field, they are shown any relevant username and passkey autofill suggestions. * If they select a passkey and authenticate successfully, they follow the `Success` path. * If they enter their username and password (local authentication), they follow the `Outcome` path to the [Data Store Decision node](data-store-decision.html). This node validates their credentials and authenticates the user if they're valid. * If they click the Sign in with passkey button, they can select a saved passkey to authenticate with. If authentication is successful, they follow the `Success` path. ## Availability | Product | Available? | | ------------------------------------- | ---------- | | PingOne Advanced Identity Cloud | Yes | | PingAM (self-managed) | Yes | | Ping Identity Platform (self-managed) | Yes | ## Inputs * This node requires a `username` in the incoming node state to assess whether the user has a registered device. Implement a [Platform Username node](platform-username.html) earlier in the journey. * Optionally, this node can read the contents of the `webAuthnExtensions` shared state property as input. You can populate the `webAuthnExtensions` property with any JSON object you choose using a script or in a node that occurs earlier in the journey. If this property is populated, its contents are placed in the `extensions` entry passed to the browser or authenticator. If this property is empty, an empty JSON object is passed to the browser or authenticator. You can find more information on WebAuthn extensions in [WebAuthn Extensions](https://www.w3.org/TR/webauthn-1/#extensions). ## Dependencies For successful authentication, this node depends on: * A client that supports web authentication * A registered FIDO device To support passkey autofill, you must place this node in a v2.0 [Page node](page.html) and configure the journey with WebAuthn conditional UI. Learn more in [Configure WebAuthn conditional UI](https://docs.pingidentity.com/pingoneaic/am-authentication/authn-mfa-webauthn.html#webauthn-conditional-ui). ## Configuration | Property | Usage | Availability | | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | | 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 your tenant, for example, `openam-example.forgeblocks.com`. | All node versions | | 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. | All node versions | | 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, Advanced Identity Cloud prefers those that verify the user's identity. If none are available, Advanced Identity Cloud accepts any authenticator. - `DISCOURAGED` Advanced Identity Cloud doesn't require an authenticator that verifies the user's identity. Authenticators that don't verify the user's identity are preferred. | All node versions | | Allow recovery codes | If you select this option, Advanced Identity Cloud 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. | All node versions | | 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. Advanced Identity Cloud stores a message in the `WebAuthenticationDOMException` property of the shared state. | All node versions | | Username from device | Whether Advanced Identity Cloud 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 must enable this option for [WebAuthn conditional UI](https://docs.pingidentity.com/pingoneaic/am-authentication/authn-mfa-webauthn.html#webauthn-conditional-ui) and [usernameless authentication](https://docs.pingidentity.com/pingoneaic/am-authentication/authn-mfa-webauthn.html#webauthn-usernameless). | All node versions | | Return challenge as JavaScript (Legacy) | This is a legacy option. You should make sure it's deselected.When not enabled, the node returns the challenge and associated data in a metadata callback. Advanced Identity Cloud uses the information from the callback to interact with WebAuthn APIs on its behalf. | [v1.0 only](#v2) | | Detect sign count mismatch | The sign count is useful for detecting potential cloned devices. It's stored in the WebAuthn device profile as `signCount`.If you enable this option, the node compares the authenticator's sign count ([signature counter](https://www.w3.org/TR/webauthn-2/#signcount)) with the sign count stored in the user's profile.If the authenticator sign count is less than or equal to the stored value, evaluation continues to the [Sign Count Mismatch](#sign-count-mismatch) outcome. | All node versions | | Mediation AM only *(tooltip: Currently available only in AM 8.1)* | The mediation used by the browser, which determines how the browser handles WebAuthn.The available options are:- DEFAULT The browser uses its default mediation. - CONDITIONAL The browser uses the WebAuthn *conditional UI*, also known as *passkey autofill*, for authentication. * To show users relevant passkeys as autofill suggestions when they're prompted for their username, select this option and make sure the Autocomplete Values property in [Platform Username node](platform-username.html) includes `username` and `webauthn`, in this order. * To show users a Sign in with passkey button, select this option and the Authentication Button option.Learn more in [Configure WebAuthn conditional UI](https://docs.pingidentity.com/pingoneaic/am-authentication/authn-mfa-webauthn.html#webauthn-conditional-ui). | [v2.0](#v2) | | Authentication Button AM only *(tooltip: Currently available only in AM 8.1)* | This option only applies if Mediation is set to `CONDITIONAL`. Select this option to display a Sign in with passkey button. This lets the user manually trigger the passkey flow, which is useful for users who have a physical passkey device, such as a YubiKey. It also provides passkey functionality to browsers that don't support the conditional UI. | [v2.0](#v2) | ## 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. * On successful authentication, the node adds the UUID of the device (`webauthnDeviceUuid`) and the name of the device (`webauthnDeviceName`) to the shared state. This lets you track the use of biometric authentication and the device used to authenticate. * On successful authentication, the node adds a `webauthnAssertionInfo` object to the transient state. The `webauthnAssertionInfo` object includes the following information: ```json { "authenticatorAttachment": "platform", "flags": { "UP": true, "UV": true, "ED": false, "AT": false, "BE": true, "BS": true } } ``` The `authenticatorAttachment` field is only populated when the UI or client application supports sending it. This field lets the journey identify whether the device used to authenticate was a roaming (cross-platform) device or a client-bound (platform) device. Learn more in [Authenticator Attachment Modality](https://www.w3.org/TR/webauthn-1/#sctn-authenticator-attachment-modality) in the WebAuthn specification. The `flags` provide additional information about the authenticator. Learn more about these flags in [Authenticator Data](https://www.w3.org/TR/webauthn-1/#sec-authenticator-data) in the WebAuthn specification. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | * With the exception of the `webauthnAssertionInfo` object, the contents of the transient state for this node aren't public. Don't rely on them in your scripts. | ## Callbacks The node sends the following callbacks: * `ConfirmationCallback` Lets the user choose to provide a recovery code rather than authenticate using a device. * `HiddenValueCallback` Contains a placeholder when initially sent but when the client sends it back, it contains the WebAuthn result payload. * `MetadataCallback` Contains the challenge and associated data. > **Collapse: Example** > > The following example shows a `MetadataCallback` where the WebAuthn conditional UI is enabled with a Sign in with passkey button: > > ```json > { > "type": "MetadataCallback", > "output": [ > { > "name": "data", > "value": { > "_action": "webauthn_authentication", > "_type": "WebAuthn", > "supportsJsonResponse": true, > "challenge": "8Kx0tYt5tFZ7t7aO5T5x2w==", > "allowCredentials": [], > "_allowCredentials": [], > "timeout": "60000", > "userVerification": "preferred", > > "conditional": true, > "mediation": "conditional", > "manualButtonEnabled": true, > > "allowRecoveryCode": "false", > "relyingPartyId": "rpId: \"example.com\",", > "_relyingPartyId": "example.com", > "extensions": {} > } > } > ] > } > ``` In v1.0 of the node, the `MetadataCallback` is only sent with the challenge and associated data when Return challenge as JavaScript is not selected. * `ScriptTextOutputCallback` This callback is only sent in v1.0 of the node. Contains the challenge and associated data as embedded JavaScript (`scriptContext`) that can interact directly with the WebAuthn API if Return challenge as JavaScript is selected. The information included in the `scriptContext` is the same as what's included in the `MetadataCallback` but formatted as JavaScript. Learn more in [Supported callbacks](https://docs.pingidentity.com/pingoneaic/am-authentication/callbacks-supported.html). ## 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`. Learn more in [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. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | * User 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 Advanced Identity Cloud accept and verify the recovery code. - `Sign Count Mismatch` If Detect sign count mismatch is enabled and the authenticator sign count is less than or equal to the value stored in the user's profile, evaluation continues to the Sign Count Mismatch outcome. This outcome can help to detect cloned or malfunctioning authenticators. A sign count mismatch doesn't necessarily indicate that the operation was performed by a cloned authenticator. Address this situation appropriately for your deployment, for example, by using a scripted decision node. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The node itself is considered to have succeeded even if evaluation leads to this outcome. Therefore, if it suits your deployment, you can design your journey to continue through this outcome. | ## Changelog | Version | Changes | | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | []()2.0 AM only *(tooltip: Currently available only in AM 8.1)* | * Added the Mediation and Authentication Button configuration options. * Removed the Return challenge as JavaScript configuration option. |