WebAuthn Registration node

The WebAuthn Registration node lets users of supported clients register FIDO2 devices for use during authentication.

PingOne 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

Compatibility

Product	Compatible?
Advanced Identity Cloud	Yes
PingAM (self-managed)	Yes
Ping Identity Platform (self-managed)	Yes

Product

Compatible?

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 the Platform Username node and Platform Password node before this node 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.

Dependencies

You must configure the WebAuthn Profile Encryption service to use this node.

Configuration

Property Usage

Relying party

The name of the 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

Relying party identifier

The domain used as the relying party identifier during WebAuthn. If not specified, AM uses the domain name of the instance, such as am.example.com.

Specify an alternative domain if your AM instances are behind a load balancer.

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.

User verification requirement

The required level of user verification.

The available options are:

REQUIRED: The authenticator must verify the identity of the user, for example, by using biometrics. PingOne Advanced Identity Cloud filters out authenticators that don’t verify user identity and the user can’t select them.
PREFERRED: PingOne Advanced Identity Cloud prefers an authenticator that verifies user identity. If none are available, PingOne 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

Preferred mode of attestation

Indicates whether the authenticator must provide attestation statements.

The available options are:

NONE: PingOne Advanced Identity Cloud doesn’t require the authenticator to provide attestation statements. If the authenticator sends attestation statements, PingOne Advanced Identity Cloud doesn’t verify them and the process doesn’t fail.
INDIRECT: PingOne Advanced Identity Cloud doesn’t require the authenticator to provide attestation statements. However, if the authenticator sends attestation statements, PingOne Advanced Identity Cloud verifies them and the process fails if the verification fails.
DIRECT: PingOne Advanced Identity Cloud requires the authenticator to provide attestation statements and verifies them. The process fails if the attestation statements can’t be verified.

PingOne Advanced Identity Cloud supports the following attestation formats:

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.

Specifically, PingOne Advanced Identity Cloud does not support the Android Key Attestation Statement Format.

Accepted signing algorithms

The algorithms authenticators can use to sign their assertions.

Authentication attachment

If specified, PingOne 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: PingOne 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.

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.

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 PingOne Advanced Identity Cloud can verify.

If you disable this setting, PingOne 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.

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.

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.

Generate recovery codes

Indicates whether PingOne Advanced Identity Cloud generates WebAuthn-specific recovery codes. If enabled, PingOne Advanced Identity Cloud generates recovery codes and stores them in the transient state if registration is successful.

Use the Recovery Code Display node 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 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.

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.

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 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.

Username to device

This option specifies that 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 can find information on using this property for usernameless authentication with ForgeRock Go in Configure usernameless authentication with ForgeRock Go.

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, PingOne 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.

You can find information on using this property for usernameless authentication with ForgeRock Go in Configure usernameless authentication with ForgeRock Go.

Return challenge as JavaScript

If enabled, the node returns its challenge as a fully encapsulated client-side JavaScript that interacts directly with the WebAuthn API and submits the response.

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 uses the information from the callback to interact with the WebAuthn API on behalf of PingOne Advanced Identity Cloud.

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.

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.

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:
- Information provided by the device is stored in the webauthnData property.
- The attestation type achieved is stored in the webauthnAttestationType property.

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 PingOne Advanced Identity Cloud encounters an issue when attempting to register a user’s device, evaluation continues along the Failure outcome path. For example, if PingOne 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.

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.

Example

The following sample journey registers WebAuthn devices:

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, AM prompts the user to register an authenticator:

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, 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, , and click Rename.

Any problems encountered during the registration, including a timeout, results in the evaluation continuing to the Failure outcome.