MFA: Web Authentication (WebAuthn)

Web Authentication allows users to authenticate by using an authenticator device, for example the fingerprint scanner on their laptop or phone.

Communication with the authentication devices is handled by the user’s browser. AM requests that the browser activates authenticators with certain criteria; for example it must be built-in to the platform rather than a roaming USB device, and/or that it must verify the identity of the user, rather than simply that a user is present.

To use WebAuthn with AM, users must first register their authenticators. If recovery codes are enabled, users must also make a copy of their codes.

Registration involves the selected authenticator creating, or minting, a key pair. The public key of the pair is returned to AM and stored in the user’s profile. The private key is stored securely, either in the authenticator itself, or in the platform managing the authenticators. The private key does not leave the client at any time.

When authenticating by using WebAuthn, the authenticator locks some data using the stored private key, which is sent to AM to verify using the public key stored in the user’s profile. If the data is verified as being from the correct device, and passes any attestation checks, the authentication is considered successful.

AM supports web authentication in the following user agents and platform minimum versions:

Minimum Web Authentication User Agent Versions
User Agent Platform Version Supported?

Google Chrome

Desktop

70

Android

70

Microsoft Edge

Desktop

18

Mozilla Firefox

Desktop

60

Creating Trees for Web Authentication (WebAuthn)

This section explains how to create an authentication tree to authenticate users by using a WebAuthn device, and allow them to register a device if they have not already done so.

If the user has already registered a WebAuthn device, they only need to enter their username, and then perform the authorization gesture with their registered device to access their profile.

If the user does not have a registered device, they are prompted for their password, and must be verified by the Data Store Decision Node before registering a new WebAuthn device. Once completed, they must authenticate with the new device before gaining access to their profile page.

To Create a Tree for WebAuthn Registration and Authentication

This procedure assumes the following:

  • The WebAuthn Profile Encryption Service is configured.

    This service specifies the attribute in which to store information about registered WebAuthn devices, and whether to encrypt that information.

    For detailed information about the available properties, see WebAuthn Profile Encryption Service.

The tree created in this procedure is an example, and does not provide user-friendly features, such as allowing retries of the users' password.

To create a multi-factor authentication tree for WebAuthn authentication, and registration if required, perform the following steps:

  1. In the AM Admin UI, go to Realms > Realm Name > Authentication > Trees.

  2. Create the authentication tree as follows:

    • Click Create Tree.

      The New Tree page appears.

    • Specify a name of your choosing, for example, myWebAuthnTree, and then click Create.

      The authentication tree designer is displayed, with the Start entry point connected to the Failure exit point.

      You can add nodes to the authentication tree by dragging the node from the Components panel on the left-hand side and dropping it into the designer area.

    • Add the following nodes to the authentication tree:

    • Connect the nodes as demonstrated in the following figure:

      An authentication tree setup for WebAuthn authentication.
    • Save your changes.

  3. Test your WebAuthn authentication and registration tree as follows:

    • Log out of AM, and then go to a URL similar to the following: https://tenant-name.forgeblocks.com/am/XUI/?realm=/alpha&service=myWebAuthnTree#login

      You must connect over HTTPS in order to use Web Authentication.

      A login screen prompting you to enter your user ID appears.

    • Enter the username of an existing account in the specified realm. For example, enter demo.

    • If the demo user does not have a registered device:

      • When asked for the user’s password, enter the default Ch4ng31t.

      • At the following screen, register a WebAuthn authenticator by performing an authorization gesture, for example press the button on a connected Yubikey.

        trees-node-webauthn-waiting
        Figure 1. The WebAuthn Registration node waiting for 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.

        If the device registration is successful, the user is redirected to the new node in the tree in order to authenticate with the newly registered device.

    • When prompted, authenticate to AM by performing an authorization gesture with a registered device.

      If the authorization is verified, the user’s profile page is displayed.

      • Click the Dashboard link to see a list of the registered WebAuthn authenticators, and to rename or delete them. The default name for a new device is New Security Key.

Configuring Usernameless Authentication with ForgeRock Go

With ForgeRock Go, you can create a secure and seamless login experience by authenticating with any credential on the user’s device that supports FIDO2 WebAuthn.

You can also extend passwordless authentication to include usernameless authentication with popular authenticators that support resident keys; for example, Windows Hello (biometric authenticators).

To use usernameless authentication, you must register an authenticator that supports resident keys to the user’s profile, and enable the option to associate a certificate on the device with the user’s username.

Once registered, that device can be used to authenticate the user without them having to provide their credentials; they just have to select the appropriate entry to use from the list their device provides.

To Configure Usernameless Authentication with ForgeRock Go

To Configure Usernameless Authentication with ForgeRock Go, create a Web Authentication registration tree to associate a device that supports resident keys with a user. The registration tree is similar to that described in Creating Trees for Web Authentication (WebAuthn).

Create a second tree that lets users authenticate to AM without entering their username or password, by using Forgerock Go.

The trees in this procedure are examples, and do not provide user-friendly features, such as allowing retries, or redirecting to further help on failures.

  1. In the AM Admin UI, select the realm that will contain the ForgeRock Go registration tree.

  2. Create the registration tree as follows:

    • Select Authentication > Trees, and then click Create Tree.

      The New Tree page appears.

    • Specify a name of your choosing, for example, fr-go-reg, and then click Create.

      The authentication tree designer is displayed, with the Start entry point connected to the Failure exit point.

      You can add nodes to the authentication tree by dragging the node from the Components panel on the left side and dropping it into the designer area.

    • Add the following nodes to the authentication tree:

      • Platform Username Node

      • Platform Password Node

      • WebAuthn Authentication Node

      • Data Store Decision Node

      • (Optional) Scripted Decision Node

        When configured for ForgeRock Go, the WebAuthn Registration node will store the value of the username authentication tree shared state variable in the device by default. This value will later be used to identify the user during authentication.

        Use a Scripted Decision Node to customize the display name or string to be saved in the shared state. You will later configure the variable containing the data in the WebAuthn Registration node.

        Example JavaScript To Create Display Names
        var username = sharedState.get("username");
        var displayName = '';
        
        var fullName = idRepository.getAttribute(username, "CN").iterator().next();
        var email = idRepository.getAttribute(username, "mail").iterator().next();
        
        if(fullName){
            displayName += fullName;
        }
        
        if(email){
            displayName += ' (' + email + ')';
        }
        
        sharedState.put("displayName", displayName.toString());
        outcome = "continue";
      • (Optional) Page Node

    • Connect the nodes as demonstrated in the following figure:

      An authentication tree setup for ForgeRock Go device registration.
    • In the WebAuthn Registration node properties, ensure Username to device is enabled.

    • (Optional) If you are using a Scripted Decision node to create the display name, enter the shared state variable name into the Shared state attribute for display name property in the WebAuthn Registration node.

    • (Optional)

      If you are not using the Scripted Decision node to create the display name, enter userName into the Shared state attribute for display name property in the WebAuthn Registration node.

    • Save your changes.

  3. Create an authentication tree for ForgeRock Go, and specify a name of your choosing; for example, fr-go-auth.

    • Add a WebAuthn Authentication Node to the authentication tree.

    • Connect the nodes as demonstrated in the following figure:

      An authentication tree setup for ForgeRock Go device authentication.
    • In the WebAuthn Authentication node properties, ensure Username from device is enabled.

    • Save your changes.

  4. You are now ready to register a device, and authenticate by using ForgeRock Go.

Registering and Authenticating with ForgeRock Go

Follow these steps to register a device for use with usernameless authentication, and then authenticate without having to provide your username or password.

  1. To register a device for use with ForgeRock Go:

    • Log out of AM, and then go to your ForgeRock Go registration tree, with a URL similar to the following: https://tenant-name.forgeblocks.com/am/XUI/?realm=/alpha&service=fr-go-reg#login

      You must connect over HTTPS in order to use Web Authentication.

      A login screen prompting you to enter your credentials appears.

    • Enter the username and password of an existing account in the specified realm. For example, enter demo, and the password Ch4ng31t, and then click Log In.

    • If you are authenticating from a FIDO2-enabled device, a dialog will display asking you to choose the method to verify your identity; for example, a USB security key, or built-in biometric sensor.

      Select the option you want to associate with the user.

    • Perform the authorization gesture of the chosen option when asked to do so. For example, scan your fingerprint with TouchID, or press the button on your USB security key.

      If successful, you are taken to the profile page for the user.

    • The new device appears on the Dashboard page, as New Security Key.

      Give a suitable name to the device; for example, Apple Mac TouchID, by clicking the context icon, , and selecting Settings.

  2. To use a device to authenticate without username or password by using ForgeRock Go:

    • Log out of AM, and then go to your ForgeRock Go authentication tree, with a URL similar to the following: https://tenant-name.forgeblocks.com/am/XUI/?realm=/alpha&service=fr-go-auth#login

      You must connect over HTTPS in order to use Web Authentication.
    • Perform the authorization gesture of the chosen option when asked to do so. For example, scan your fingerprint with TouchID, or press the button on your USB security key.

      If successful, a list of the accounts associated with the authentication device displays:

      Google Chrome presenting the accounts associated with TouchID on the device.

      Note that in this example the user’s full name and email address appear, which were gathered by the Scripted Decision node from the user’s profile during registration.

    • Select the account that you want to sign in.

      If successful, you are taken to the profile page for the user, without having to enter username or password credentials!