--- title: WebAuthn Registration node description: The WebAuthn Registration node lets users of supported clients register FIDO2 devices for use during authentication. component: auth-node-ref version: latest page_id: auth-node-ref::webauthn-registration canonical_url: https://docs.pingidentity.com/auth-node-ref/latest/webauthn-registration.html keywords: ["Nodes & Trees", "Journeys", "Authentication"] page_aliases: ["auth-node-webauthn-registration.adoc"] superseded_by: https://docs.pingidentity.com/auth-node-ref/latest/webauthn-registration.html section_ids: example: Example availability: Availability inputs: Inputs dependencies: Dependencies configuration: Configuration outputs: Outputs callbacks: Callbacks outcomes: Outcomes changelog: Changelog --- # WebAuthn Registration node The WebAuthn Registration node lets users of supported clients register FIDO2 devices for use during authentication. > **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. | Advanced Identity Cloud interacts with FIDO2/WebAuthn capable browsers, such as `Chrome`, `Firefox` and `Microsoft Edge`. These browsers interact with the following: * Client to Authenticator Protocol 2 (CTAP2) authenticators, including Universal 2nd Factor (U2F) and FIDO2 Security Keys * Platforms such as Windows Hello and Apple Touch ID ## Example The following sample journey registers WebAuthn devices: ![WebAuthn device registration](_images/trees-node-webauthn-reg-example-platform.png) If the user's client doesn't support WebAuthn, the failure URL is altered, for example to redirect the user to a page explaining which clients and operating systems support WebAuthn. If the user's client does support WebAuthn, and the connection is secured with TLS, Advanced Identity Cloud prompts the user to register an authenticator: ![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 registration. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------ | | | 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 registration depend on the value of the properties in the node. For example, if the User verification requirement property is set to `REQUIRED`, the client would not activate a USB hardware security key for registration. 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, the evaluation continues along the `Success` outcome path, and in this example will be taken to their profile page. The registered authenticator appears on the user's dashboard page, with the label *New Security Key*. To rename the authenticator, click its vertical ellipsis context icon, [icon: ellipsis-v, set=fa], and click Rename. Any problems encountered during the registration, including a timeout, results in the evaluation continuing to the `Failure` outcome. ## Availability | Product | Available? | | ------------------------------------- | ---------- | | PingOne Advanced Identity Cloud | Yes | | PingAM (self-managed) | Yes | | Ping Identity Platform (self-managed) | Yes | ## Inputs * This node requires the `username` and `password` properties in the incoming node state. Implement a [Platform Username node](platform-username.html) and a [Platform Password node](platform-password.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 You must configure the WebAuthn Profile Encryption service to use this node. Learn more in [Configure the WebAuthn Profile Encryption service](https://docs.pingidentity.com/pingoneaic/am-authentication/authn-mfa-webauthn.html#mfa-webauthn-profile-encryption). ## Configuration | Property | Usage | Availability | | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | | Relying party | The name of the [relying party](https://www.w3.org/TR/webauthn/#webauthn-relying-party) entity that registers and authenticates users by using WebAuthn. This could be the name of the organization, realm, and so on.For example, `Example.com` | All node versions | | Relying party identifier | The domain used as the [relying party identifier](https://www.w3.org/TR/webauthn/#relying-party-identifier) during WebAuthn. If not specified, Advanced Identity Cloud uses the domain name of the instance, such as `am.example.com`. | All node versions | | Origin domains | A set of fully-qualified URLs of accepted origins, for example `http://app.example.com:443`. If empty, the accepted origin is the incoming request origin. | All node versions | | User verification requirement | The required level of [user verification](https://www.w3.org/TR/webauthn/#user-verification).The available options are:- `REQUIRED` The authenticator must verify the identity of the user, for example, by using biometrics. Advanced Identity Cloud filters out authenticators that don't verify user identity and the user can't select them. - `PREFERRED` Advanced Identity Cloud prefers an authenticator that verifies user identity. If none are available, Advanced Identity Cloud accepts any authenticator. - `DISCOURAGED` The authenticator doesn't need to verify the identity of the user. Authenticators that don't verify user identity are preferred.Default: `PREFERRED` | All node versions | | Preferred mode of attestation | Indicates whether the authenticator must provide attestation statements.The available options are:- `NONE` Advanced Identity Cloud doesn't require the authenticator to provide attestation statements. If the authenticator sends attestation statements, Advanced Identity Cloud doesn't verify them and the process doesn't fail. - `INDIRECT` Advanced Identity Cloud doesn't require the authenticator to provide attestation statements. However, if the authenticator sends attestation statements, Advanced Identity Cloud verifies them and the process fails if the verification fails. - `DIRECT` Advanced Identity Cloud requires the authenticator to provide attestation statements and verifies them. The process fails if the attestation statements can't be verified.Advanced Identity Cloud supports the following attestation formats:- [None](https://www.w3.org/TR/webauthn/#sctn-none-attestation) - [Android SafetyNet](https://www.w3.org/TR/webauthn/#sctn-android-safetynet-attestation) - [Android Key](https://www.w3.org/TR/webauthn/#sctn-android-key-attestation) - [Packed](https://www.w3.org/TR/webauthn/#sctn-packed-attestation) - [FIDO U2F](https://www.w3.org/TR/webauthn/#sctn-fido-u2f-attestation) - [TPM](https://www.w3.org/TR/webauthn/#sctn-tpm-attestation) If your end users use an authenticator that provides attestation statements in a format other than these supported formats, you must set the Preferred mode of attestation property to NONE. | All node versions | | Accepted signing algorithms | The algorithms authenticators can use to sign their assertions. | All node versions | | Authentication attachment | If specified, Advanced Identity Cloud filters out authenticators that don't match the attachment type.There are two attachment types:- A `PLATFORM` authenticator is part of the device, for example, a fingerprint scanner built-in to a phone or laptop. - A `CROSS_PLATFORM` authenticator can be removed from a device and used elsewhere, for example, a USB hardware security key.Available options for this property are:- `UNSPECIFIED` Advanced Identity Cloud accepts any attachment type. - `PLATFORM` The authenticator must be a *platform* attachment type. The client shouldn't activate other authenticator types for registration. - `CROSS_PLATFORM` The authenticator must be a *cross-platform* attachment type. The client shouldn't activate other authenticator types for registration. | All node versions | | Trust Store alias | The alias of the realm trust store holding the secrets necessary to validate a supplied attestation certificate. The alias can only contain the characters `a-z` and periods (`.`).This value is appended to the string `am.authentication.nodes.webauthn.truststore.` to form the dynamic secret label used to map certificate chains. | All node versions | | Enforce revocation check | Whether to enforce the checking of revocation entries from certificates.If you enable this setting, any attestation certificate's trust chain *must* have a CRL or OCSP entry that Advanced Identity Cloud can verify.If you disable this setting, Advanced Identity Cloud doesn't check presented certificates for revocation. Certificates downloaded from the FIDO Metadata Service might not have a CRL or OCSP entry. You must remove expired or revoked certificates manually. | All node versions | | Timeout | 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. | All node versions | | Limit registrations | Indicates whether the same authenticator can be registered multiple times.If you enable this property, the client won't activate an authenticator that's already registered for registration. | All node versions | | Generate recovery codes | Indicates whether Advanced Identity Cloud generates WebAuthn-specific recovery codes. If enabled, Advanced Identity Cloud generates recovery codes and stores them in the transient state if registration is successful.Use the [Recovery Code Display node](recovery-code-display.html) to display the codes to the user for safe-keeping.Don't enable this property if you've enabled the Store device data in transient state property (and aren't saving the device data to the user's profile immediately). Enable the Generate recovery codes property in the [WebAuthn Device Storage node](webauthn-device-storage.html) instead. Generating recovery codes overwrites all existing WebAuthn-specific recovery codes. Only the most recent set of recovery codes can be used for authentication if a device has been lost or stolen. | All node versions | | Store data in transient state | If you enable this property, the node stores the following data in transient state:- Information provided by the device is stored in the `webauthnData` property for later analysis by subsequent nodes. - The attestation type achieved (`BASIC`, `CA`, or `SELF`) is stored in the `webauthnAttestationType` property. The amount of data received from the device can be large. Only enable this option if you intend to analyze it. | All node versions | | Store device data in transient state | If you enable this property, information about the device required for WebAuthn is stored in transient state instead of saved immediately to the user's profile.Enable this option under the following conditions:- You've enabled the Store data in transient state property - You need to make decisions in scripts based on the outcome of the analysis of data in transient state - You don't want to register the device to the user until the analysis is complete Don't change the data while it's in transient state, nor when it's saved to a user's profile. Changing the device data will likely cause the device to be unable to authenticate.If you enable this option, use the [WebAuthn Device Storage node](webauthn-device-storage.html) to write the device data to the user's profile.If this option is disabled, device data is written automatically to the user's profile when registration is successful. | All node versions | | Username to device | Whether the device should store the user's username.If you enable this option, devices that don't support storing and providing the username won't be able to use this node. If the device can't store or provide usernames, the node fails and the journey follows the Failure outcome.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 | | Shared state attribute for display name | The share state property that contains a display name for the user. For example, their full name, or email address.When Username to device is enabled, Advanced Identity Cloud writes the value stored in this property to devices in addition to the username. This helps the user select between the accounts they may have on their devices.If you don't set this property, or if the variable isn't found in shared state, the username is used.Find more information on using this property in [Configure 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) | | Maximum Saved Devices | The maximum number of WebAuthn devices that can be stored in the user's profile.Set this property to `0` if you don't want to limit the number of devices.When this property is greater than zero, the `Exceed Device Limit` outcome path becomes available. You can only limit the number of devices stored in the user's profile. If you enable Store device data in transient state, the node can't limit the number of devices and the Exceed Device Limit outcome path isn't displayed. In this case, specify the maximum number of saved devices in the WebAuthn Device Storage node. | All node versions | | Validate FIDO-U2F attestation AAGUID | If enabled, the node validates the Authenticator Attestation Global Unique Identifier (AAGUID) for any FIDO-U2F attestation type. The AAGUID must be 16 bytes, initialized with all zeros. | All node versions | | FIDO Certification Level | The minimum FIDO certification level that the device's certification status must satisfy during a registration flow\.If this setting is `Off` (the default), Advanced Identity Cloud doesn't check the metadata service for the device's certification level.Other options include:- `Self Assertion Submitted`: Use this setting if your authenticator has been submitted for FIDO certification but has not yet been certified. - `FIDO Certified L1` - `FIDO Certified L3+`: Find information on these levels in [Certified Authenticator Levels](https://fidoalliance.org/certification/authenticator-certification-levels/). You must configure the WebAuthn Metadata service for the realm to enforce a FIDO certification check. Find more information on this service in WebAuthn Metadata service. | All node versions | ## Outputs * The node passes the contents of the `webAuthnExtensions` property to the browser or authenticator. * If a timeout is reached, or any other client error occurs, the error type and description are added to the `WebAuthenticationDOMException` shared state property. * If Shared state attribute for display name is set, the node writes the username or display name to shared state as a value of the specified property. * If Store data in transient state is set, the node writes the following data to transient state on successful registration: * Information provided by the device is stored in the `webauthnData` property. * The attestation type achieved is stored in the `webauthnAttestationType` property. * The registered Authenticator Attestation Global Unique Identifier (AAGUID) is stored in the `webauthnDeviceAaguid` property. ## Callbacks The node sends the following callbacks: * `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** > > ```json > { > "type": "MetadataCallback", > "output": [ > { > "_type": "WebAuthn", > "_action": "webauthn_registration", > "supportsJsonResponse": true, > "challenge": "bXktcmFuZG9tLWNoYWxsZW5nZQ==", > "attestationPreference": "none", > "userName": "bjensen", > "userId": "am9obmRvZUBleGFtcGxlLmNvbQ==", > "relyingPartyName": "Example Org", > "authenticatorSelection": "{\"userVerification\":\"preferred\",\"residentKey\":\"discouraged\",\"requireResidentKey\":false}", > "_authenticatorSelection": { > "userVerification": "preferred", > "residentKey": "discouraged", > "requireResidentKey": false > }, > "pubKeyCredParams": "[{\"type\":\"public-key\",\"alg\":-7},{\"type\":\"public-key\",\"alg\":-257}]", > "_pubKeyCredParams": [ > { > "type": "public-key", > "alg": -7 > }, > { > "type": "public-key", > "alg": -257 > } > ], > "timeout": "60000", > "excludeCredentials": "[{\"type\":\"public-key\",\"id\":\"Y3JlZC0x\"}]", > "_excludeCredentials": [ > { > "type": "public-key", > "id": "Y3JlZC0x" > } > ], > "displayName": "Babs Jensen", > "relyingPartyId": "id: \"example.com\",", > "_relyingPartyId": "example.com", > "extensions": { > "exampleExtension": true > } > } > ] > } > ``` 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 WebAuthn, evaluation continues along the `Unsupported` outcome path. For example, clients connected over the HTTP protocol rather than HTTPS don't support WebAuthn. * Success If the user successfully registers an authenticator of the correct type as determined by the node's properties, evaluation continues along the `Success` outcome path. * Failure If Advanced Identity Cloud encounters an issue when attempting to register a user's device, evaluation continues along the `Failure` outcome path. For example, if Advanced Identity Cloud can't 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 register using a device, for example, if the timeout was reached, evaluation continues along the `Client Error` outcome path. The node follows this outcome whenever the client throws a `DOMException`, as required by the [WebAuthn specification](https://www.w3.org/TR/webauthn/). | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | If a client error occurs, the error type and description are added to the `WebAuthenticationDOMException` shared state property. If required, this property can be read by nodes later in the journey. | * Exceed Device Limit If the Maximum Saved Devices property is an integer greater than zero, and registering a new device would take the number of devices above the specified threshold, evaluation continues down the `Exceed Device Limit` outcome path. In this case, you might need to instruct users to log in with an existing device to remove one or more of their registered devices. ## Changelog | Version | Changes | | --------------------------------------------------------------- | ---------------------------------------------------------------- | | []()2.0 AM only *(tooltip: Currently available only in AM 8.1)* | Removed the Return challenge as JavaScript configuration option. |