WebAuthn Authentication node

The WebAuthn Authentication node lets users on supported clients authenticate using a registered FIDO device.

Compatibility

Product	Compatible?
ForgeRock Identity Cloud	Yes
ForgeRock Access Management (self-managed)	Yes
ForgeRock Identity Platform (self-managed)	Yes

Product

Compatible?

ForgeRock Identity Cloud

Yes

ForgeRock Access Management (self-managed)

Yes

ForgeRock 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 the Platform Username node as an input to the WebAuthn Authentication node.

Prerequisites

For successful authentication, this node depends on:

A client that supports web authentication
A registered FIDO device

Configuration

Property Usage

Property	Usage
Relying party identifier	The domain used as the 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`.
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.
User verification requirement	The required 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, Identity Cloud prefers those that verify the user’s identity. If none are available, Identity Cloud accepts any authenticator. `DISCOURAGED` Identity Cloud doesn’t require an authenticator that verifies the user’s identity. Authenticators that don’t verify the user’s identity are preferred.
Allow recovery codes	If you select this option, 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 to collect and verify the recovery code.
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. Identity Cloud stores a message in the `WebAuthenticationDOMException` property of the shared state.
Username from device	Specifies whether 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. For information on using this property for usernameless authentication with ForgeRock Go, refer to Configure usernameless authentication with ForgeRock Go.
Return challenge as JavaScript	If you enable this option, the node returns its challenge as a fully encapsulated client-side JavaScript that interacts directly with the WebAuthn API and submit the response back. If this option is 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 Identity Cloud’s behalf.

Relying party identifier

The domain used as the 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.

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.

User verification requirement

The required 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, Identity Cloud prefers those that verify the user’s identity. If none are available, Identity Cloud accepts any authenticator.
DISCOURAGED: Identity Cloud doesn’t require an authenticator that verifies the user’s identity. Authenticators that don’t verify the user’s identity are preferred.

Allow recovery codes

If you select this option, 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 to collect and verify the recovery code.

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. Identity Cloud stores a message in the WebAuthenticationDOMException property of the shared state.

Username from device

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

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

Return challenge as JavaScript

If you enable this option, the node returns its challenge as a fully encapsulated client-side JavaScript that interacts directly with the WebAuthn API and submit the response back.

If this option is 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 Identity Cloud’s behalf.

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. For more information, refer to Is origin potentially trustworthy?.
No Device Registered: If the user doesn’t have a registered device, evaluation continues along the No Device Registered outcome path.
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 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 to let Identity Cloud accept and verify the recovery code.

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.

The contents of the transient state for this node aren’t public. Don’t rely on them in your scripts.

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