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 Platform Username node for this.
No Device Registered
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
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
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.
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,
Specify an alternative domain if your AM instances are behind a load balancer, for example.
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:
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
Specify the number of seconds to wait for a response from an authenticator.
If the specified time is reached, evaluation continues along the
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
For information on using this property for usernameless authentication with ForgeRock Go, refer to Configure usernameless authentication with ForgeRock Go.
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.
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
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
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
including a timeout, or to the
Client Error outcome, resulting in an authentication failure.