WebAuthn Authentication node

Lets users on supported clients use a registered FIDO device during authentication.

To determine whether the user has a registered device, the shared node state must a username. You can use a Username Collector node for this.

Outcomes

Unsupported
No Device Registered
Success
Failure
Client Error
Recovery Code (configurable)

If the user’s client does not support web authentication, evaluation continue along the Unsupported outcome path. For example, clients connected over the HTTP protocol rather than HTTPS do not support WebAuthn; however, HTTPS may not be required when testing locally, on http://localhost. For more information, refer to Is origin potentially trustworthy?.

If the user does not have a registered device, evaluation continues along the No Device Registered outcome path.

If AM encounters an issue when attempting to authenticate using the device, evaluation continues along the Failure outcome path. For example, AM could not verify that 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 authenticate using the device, for example, if the timeout was reached, 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 Allow recovery code is enabled, AM provides the user the option to enter a recovery code rather than authenticate using a device. Evaluation continues along the Recovery Code outcome path if the users chooses to enter a recovery code. To accept and verify the recovery code, ensure the outcome path leads to a Recovery Code Collector Decision node.

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.

Properties

Property Usage

Property	Usage
Relying party identifier	Specifies the domain used as the relying party identifier during web authentication. If not specified, AM uses the domain name of the instance, for example, `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 authentication. `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.
Allow recovery codes	Specify whether to allow the user to enter one of their recovery codes instead of performing an authentication gesture. Enabling this options adds a `Recovery Code` outcome path to the node. This outcome path should lead to a Recovery Code Collector Decision node to collect and verify the recovery code.
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.
Username from device	Specifies whether AM requests that the device provides the username. When enabled, if the device is unable to store or provide usernames, the node fails and evaluation continues along the `Failure` path. 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.

Relying party identifier

Specifies the domain used as the relying party identifier during web authentication. If not specified, AM uses the domain name of the instance, for example, 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 authentication.
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.

Allow recovery codes

Specify whether to allow the user to enter one of their recovery codes instead of performing an authentication gesture.

Enabling this options adds a Recovery Code outcome path to the node. This outcome path should lead to a Recovery Code Collector Decision node to collect and verify the recovery code.

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.

Username from device

Specifies whether AM requests that the device provides the username.

When enabled, if the device is unable to store or provide usernames, the node fails and evaluation continues along the Failure path.

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.

Example

This example shows one possible implementation of the flow for authenticating with WebAuthn devices:

After verifying the users credentials against the configured data store, evaluation continues to the WebAuthn Authentication node.

If the user’s client does not support WebAuthn, authentication fails and the user does not 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 there are no registered WebAuthn devices present in the user’s profile, the failure URL is set, pointing to a flow that lets the user register a device. This stage could also be an Inner Tree Evaluator node.

If the user’s client does support WebAuthn, and the connection is secured with TLS, the user is prompted to complete an authorization gesture, for example, scanning a fingerprint, or entering a PIN:

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 depends 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 which verify the identity of the user. For extra protection, AM WILL verify the response from an authenticator matches the criteria configured for the node, and will reject—with the Failure outcome—an authentication attempt by an inappropriate authenticator type.

When the user completes an 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, 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 outcome, including a timeout, or to the Client Error outcome, resulting in an authentication failure.

AM 7.3.1

WebAuthn Authentication node

Outcomes

Properties

Example