MFA: Web Authentication (WebAuthn)

This procedure assumes the following:

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

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

2. Create the authentication tree as follows:

   1. Click Create Tree.

      The New Tree page appears.

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

   3. Add the following nodes to the authentication tree:

      • Username Collector Node

      • Password Collector Node

      • WebAuthn Authentication Node

      • Data Store Decision Node

      • WebAuthn Registration Node

   4. Connect the nodes as demonstrated in the following figure:

      Standalone AM

      
      
      
      ForgeRock Identity Platform

      
      
      

   5. Save your changes.

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

   1. Log out of AM, and then go to a URL similar to the following: https://openam.example.com:8443/openam/XUI/?realm=/alpha&service=myWebAuthnTree#login

      Important

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

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

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

   3. (Optional) If the demo user does not have a registered device:

      1. When asked for the user's password, enter the default Ch4ng31t.

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

         The WebAuthn Registration node waiting for an authenticator (Standalone AM)

         
         
         
         The WebAuthn Registration node waiting for an authenticator (ForgeRock Identity Platform)

         
         
         

         Note

         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.

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

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

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.

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

2. Create the registration tree as follows:

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

      The New Tree page appears.

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

   3. Add the following nodes to the authentication tree:

      • Username Collector Node

      • Password Collector Node

      • Data Store Decision Node

      • WebAuthn Registration 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 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

   4. Connect the nodes as demonstrated in the following figure:

      Standalone AM

      
      
      
      ForgeRock Identity Platform

      
      
      

   5. In the WebAuthn Registration node properties, ensure Username to device is enabled.

   6. (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.

   7. (Optional) (ForgeRock Identity Platform deployments) 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.

   8. Save your changes.

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

   1. Add a WebAuthn Authentication Node to the authentication tree.

   2. Connect the nodes as demonstrated in the following figure:

      Standalone AM

      
      
      
      ForgeRock Identity Platform

      
      
      

   3. In the WebAuthn Authentication node properties, ensure Username from device is enabled.

   4. Save your changes.

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

   Proceed to "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:

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

      Important

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

      A login screen prompting you to enter your credentials appears.

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

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

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

   5. (Optional) 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:

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

      Important

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

   2. 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:

      

      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.

   3. 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!

To configure trust anchors in AM, you should obtain the CA-issued certificate chains for the devices you intend to verify, and make them available to AM in a secret store.

When the relevant certificate chains are in place, configure the "WebAuthn Registration Node" with the alias of the secret store, and set Preferred mode of attestation to either DIRECT or INDIRECT.

Perform the following steps to enable trust anchors and achieve CA attestation for trusted devices:

1. Obtain the CA-issued certificate chains for the devices you want to verify.

   You may need to consult the device manufacturer to obtain the certificate chains.

2. Import the certificate chains into a keystore:

   $ keytool -import \
     -file /Downloads/vendor-a-ca.crt \
     -alias "vendor-a-devices" \
     -storetype JCEKS \
     -storepass changeit \
     -keystore /path/to/openam/security/keystores/webauthnTrustStore.jceks

   The command above imports a hypothetical trust chain from "Vendor A" into a secret store named webauthnTrustStore.jceks, located in the default AM path for keystores, /path/to/openam/security/keystores

   If they keystore does not exist, the command creates it and sets the store password to changeit; otherwise it adds the specified certificate to the secret store.

3. Repeat the previous step until the webauthnTrustStore.jceks secret store contains all of the CA-issued certificate chains for the devices you want to verify.

4. Ensure that the password to access the new webauthnTrustStore.jceks secret store is available to your AM instance; for example, by encrypting the password and adding the result to a new file named webauthnStorepass, in /path/to/openam/security/secrets/encrypted.

   For more information, see "File System Secret Volumes Secret Stores".

5. In the AM console, go to the realm containing the web authentication registration tree that will attempt CA-level attestation, navigate to Authentication > Trees, and click your registration tree.

6. Select the WebAuthn Registration Node, and in the properties pane:

   1. Set the Preferred mode of attestation property to DIRECT or INDIRECT.

   2. Set the Trust Store alias property to a string that will identify both the name of the trust store, and will be the suffix of the secret ID used for mappings; for example, webauthnTrustStore.

   3. (Optional) If you want to act upon the attestation type achieved when registering a device; for example, using a script, then you should enable the Store data in transient state property.

      When this is enabled, the WebAuthn Registration Node stores the level of attestation achieved in a variable named webauthnAttestationType, in the transient state of the tree.

      Tip

      Use code similar to the following JavaScript to read the value of webauthnAttestationType:

      var attestationLevel = transientState.get("webauthnAttestationType");

   4. Save your changes.

      For more information on the available properties, see "WebAuthn Registration Node".

7. Navigate back to the realm page, select Secret Stores, and then click Add Secret Store.

8. In Secret Store ID, enter the alias you specified in the registration node earlier; for example, webauthnTrustStore.

   Select the store type, specify the path to the store, and then click Create.

   

9. Set the Store password secret ID to the name of the file you created earlier with the encrypted value of the store password in; for example, webauthnStorepass.

   Save your changes.

10. On the Mappings tab, click Add Mapping.

11. In Secret ID, select the ID that begins with am.authentication.nodes.webauthn.truststore, and has the alias you specified earlier as the suffix. For example, am.authentication.nodes.webauthn.truststore.webauthnTrustStore.

12. Enter the alias of the certificate chains you want to use for verification, and then click Add.

    Repeat this step to add all the aliases of certificate chains you want to use for CA-level attestation:

    

13. Save your changes.

    Your registration tree is now ready to verify the attestation data against the list of configured certificate chains.