WebAuthn Registration node

Lets users of supported clients register FIDO2 devices for use during authentication.

AM interacts with FIDO2/WebAuthn capable browsers, such as Chrome, Firefox and Microsoft Edge. These browsers interact with CTAP2 authenticators, including U2F and FIDO2 Security Keys, and platforms, such as Windows Hello or 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

Outcomes

Unsupported
Success
Failure
Client Error
Exceed Device Limit

If the user’s client does not support WebAuthn, evaluation continues along the Unsupported outcome path. For example, clients connected over the HTTP protocol rather than HTTPS do not support WebAuthn.

If AM encounters an issue when attempting to register using a device, evaluation continues along the Failure outcome path. For example, AM could not verify 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 register using a device, for example, if the timeout was reached, then 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 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 the Maximum Saved Devices property is set to an integer greater than zero, and registering a new device would take the number of devices above the specified threshold, then evaluation continues down the Exceed Device Limit outcome path. In this case, you may need to instruct your users to log in with an existing device in order to remove one or more of their registered devices.

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.

Properties

Property Usage

Relying party

Specify the name of the relying party entity registering and authenticating users by using WebAuthn.

For example, Example Inc.

Relying party identifier

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

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

Preferred mode of attestation

Specifies whether AM requires that the authenticator provides attestation statements.

The available options are:

NONE: AM does not require the authenticator to provide attestation statements. If the authenticator does send attestation statements, AM will not verify them, and will not fail the process.
INDIRECT: AM does not require the authenticator to provide attestation statements. If the authenticator does send attestation statements, AM will verify them, and will fail the process if they fail verification.
DIRECT: AM requires the authenticator provides attestation statements, and will verify them. The process will fail if the attestation statements cannot be verified.

AM supports the following attestation formats:

You must set the Preferred mode of attestation property to NONE to use an authenticator that provides attestation statements in a format other than the supported formats above.

Specifically, AM does not currently support:

Accepted signing algorithms

Specify the algorithms authenticators can use to sign their assertions.

Authentication attachment

Specifies whether AM requires that the authenticator is a particular attachment type.

There are two types of authenticator attachments:

An authenticator that is built-in to the client device is labeled a platform attachment.

A fingerprint scanner built-in to a phone or laptop is an example of a platform attachment authenticator.
An authenticator that can roam, or move, between different client devices is labeled a cross-platform attachment.

A USB hardware security key is an example of a cross-platform attachment authenticator.

The available options are:

UNSPECIFIED: AM accepts any attachment type.
PLATFORM: The authenticator must be a platform attachment type. The client should not activate other authenticator types for registration.
CROSS_PLATFORM: The authenticator must be a cross-platform attachment type. The client should not activate other authenticator types for registration.

Trust Store alias

Specifies the name of a secret store configured in the realm that contains CA-issued certificate chains, which can be used to verify attestation data provided by a device.

The alias of the realm trust store holding the secrets necessary to validate a supplied attestation certificate. The alias name must only contain the characters a-z and the . symbol.

The value is also appended to the string am.authentication.nodes.webauthn.truststore. to form the dynamic secret ID used to map the certificate chains.

Enforce revocation check

Specifies whether to enforce certificate revocation checks. When enabled, then any attestation certificate’s trust chain MUST have a CRL or OCSP entry that can be verified by AM during processing.

When disabled, certificates are not checked for revocation. You must ensure expired or revoked certificates are manually removed.

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.

Limit registrations

Specify whether the same authenticator can be registered multiple times.

If enabled, the client should not activate an authenticator that is already registered for registration.

Generate recovery codes

Specify whether WebAuthn-specific recovery codes should be generated. If enabled, recovery codes are generated and stored in transient state if registration was successful.

Use the Recovery Code Display node to display the codes to the user for safe-keeping.

If you have enabled the Store device data in transient state property and are not saving the device data to the user’s profile immediately, do not enable the Generate recovery codes property in this node, but in the WebAuthn Device Storage node instead.

Generating recovery codes will overwrite 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

Specify whether the information provided by the device to the node is stored in the transient node state for later analysis by subsequent nodes, using the key webauthnData.

In addition to the information provided by the device, the type of attestation achieved; for example, BASIC, CA, SELF and so on, is stored in the transient node state, using the key webauthnAttestationType.

The amount of data involved can be large. Only enable this option if you intend to analyze it.

Store device data in transient state

Specify whether the information about the device required for WebAuthn is stored in the transient node state rather than saved immediately to the user’s profile.

Enable this option if you intend to make decisions in scripts, and have enabled the Store data in transient state property, and therefore do not want to register the device to the user until the outcome of the analysis is complete.

Do not alter the data while it is in the transient node state, nor when saved to a user’s profile.

Modifying the device data will likely cause the device to be unable to authenticate.

Use the WebAuthn Device Storage node to write the device data to the user’s profile when this option is enabled.

When disabled, device data is written automatically to the user’s profile when registration is successful.

Username to device

Specifies whether AM requests that the device stores the user’s username.

When enabled, if the device is unable to store or provide usernames, the node will fail and results in the Failure outcome.

For information on using this property for usernameless authentication with ForgeRock Go, refer to Configure usernameless authentication with ForgeRock Go.

Shared state attribute for display name

Specifies a variable in shared node state that contains a display name for the user; for example, their full name, or email address.

The value is written to devices alongside the username when the Username to device property is enabled, and helps the user select between the accounts they may have on their devices.

If not specified, or the variable is not found in shared state, the username is used.

For information on using this property for usernameless authentication with ForgeRock Go, refer to Configure usernameless authentication 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 ForgeRock SDKs, uses the information from the callback to interact with the WebAuthn API on AM’s behalf.

Maximum Saved Devices

Specifies the maximum number of WebAuthn devices stored in the user’s profile.

Set this property to 0 if you do not 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 the Store device data in transient state property is enabled then the node is unable to limit the number of devices, and the Exceed Device Limit outcome path is not displayed.

In this case, specify the maximum number of saved devices in the WebAuthn Device Storage node.

Example

The following example registers WebAuthn devices:

If the user’s client does not 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.