MFA: Open AuTHentication (OATH)

The ForgeRock Authenticator (OATH) module supports HMAC one-time password (HOTP) and time-based one-time password (TOTP) authentication as defined in the OATH standard protocols for HOTP (RFC 4226) and TOTP (RFC 6238). Both HOTP and TOTP authentication require an OATH-compliant device that can provide the password.

HOTP authentication generates the one-time password every time the user requests a new password on their device. The device tracks the number of times the user requests a new one-time password with a counter. The one-time password displays for a period of time you designate in the setup, so the user may be further in the counter on their device than on their account.

AM will resynchronize the counter when the user finally logs in. To accommodate this, you set the number of passwords a user can generate before their device cannot be resynchronized. For example, if you set the number of HOTP Window Size to 50 and someone presses the button 30 times on the user’s device to generate a new password, the counter in AM will review the passwords until it reaches the one-time password entered by the user. If someone presses the button 51 times, you will need to reset the counter to match the number on the device’s counter before the user can login to AM. HOTP authentication does not check earlier passwords, so if the user attempts to reset the counter on their device, they will not be able to login until you reset the counter in AM to match their device. For more information, see Resetting Registered Devices by using REST.

TOTP authentication constantly generates a new one-time password based on a time interval you specify. The device tracks the last several passwords generated and the current password. The TOTP Time Steps setting configures the number of passwords tracked. The Last Login Time setting monitors the time when a user logs in to make sure that user is not logged in several times within the present time period. The TOTP Time-Step Interval should not be so long as to lock users out, with a recommended time of 30 seconds.

Differences Among Authentication Modules That Support HOTP

The ForgeRock Authenticator (OATH), OATH, and HOTP authentication modules let you configure authentication that prompts users to enter HMAC one-time passwords. It is important that administrators understand the differences among these authentication modules:

  • The ForgeRock Authenticator (OATH) and OATH authentication modules accept one-time passwords generated by the end user’s device, while the HOTP authentication module generates passwords and sends them to users by e-mail or SMS.

  • All three of the authentication modules support HOTP passwords. The ForgeRock Authenticator (OATH) and OATH authentication modules also support TOTP passwords.

  • The ForgeRock Authenticator (OATH) and OATH authentication modules require users to register their devices, and store the device registration details in the user profile. The HOTP authentication module requires the presence of mobile phone numbers and/or e-mail addresses in user profiles.

  • The ForgeRock Authenticator (OATH) authentication module can encrypt stored device registration details.

Before deciding on an implementation strategy, assess your requirements against the following capabilities in AM:

Comparing the ForgeRock Authenticator (OATH) to the HOTP Authentication Module
Requirement Available With the ForgeRock Authenticator (OATH) Authentication Module? Available With the HOTP Authentication Module?

End users can authenticate using a HOTP password

AM can generate a HOTP password and send it to end users in a text message or an e-mail

End users can register a mobile phone with AM, and an authenticator app on the phone can generate a HOTP or TOTP password that AM accepts as proof of authentication

End users can authenticate with a TOTP password

End users can opt out of providing a one-time password

End users can authenticate using XUI

Creating Chains for One-Time Password Authentication

This section covers one-time password authentication.

To Create a Chain for One-Time Password Authentication

The procedure assumes the following:

  • Users will provide user IDs and passwords as the first step of multi-factor authentication.

  • An existing Data Store authentication module will collect and verify user IDs and passwords.

  • All authentication modules in the chain will use the Requisite flag setting.

  • Users can opt out of one-time password authentication.

  • The ForgeRock Authenticator (OATH) Service is configured.

    This service specifies the attribute in which to store information about the registered OATH device, and whether to encrypt that information. It also specifies the attribute used to indicate if a user has opted out of one-time passwords.

    For detailed information about the available properties, see ForgeRock Authenticator (OATH) Service.

To create a multi-factor authentication chain that uses the ForgeRock Authenticator (OATH) module, perform the following steps:

  1. In the AM Admin UI, select the realm that will contain the authentication chain.

  2. You can allow users to opt out of using OATH-based one-time passwords as follows:

    • Select Authentication > Settings > General.

    • Make sure that the Two Factor Authentication Mandatory is not enabled.

      See General for details about this configuration setting.

    For information about how letting users skip multi-factor authentication impacts the behavior of authentication chains, see Letting Users Opt Out of One-Time Password Authentication (OATH).

  3. Create a ForgeRock Authenticator (OATH) authentication module as follows:

    • Select Authentication > Modules, and then click Add Module.

      The New Module page appears.

    • Fill in fields in the New Module page as follows:

      • Name: Specify a module name of your choosing.

      • Type: Select ForgeRock Authenticator (OATH).

    • Click Create.

      A page that lets you configure the authentication module appears.

    • Configure the ForgeRock Authenticator authentication module to meet your organization’s requirements.

  4. Create the authentication chain as follows:

    • Select Authentication > Chains, and then click Add Chain.

      The Add Chain page appears.

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

      A page appears with the Edit Chain tab selected.

    • Click Add a Module. Fill in fields in the New Module dialog box as follows:

      • Select Module: Select the existing Data Store module to use in this chain.

      • Select Criteria: Select a flag setting for the module in the authentication chain. For this example, specify the Requisite flag.

    • Click OK.

      A graphic showing an authentication chain with a single Data Store module appears on the page.

    • Add the ForgeRock Authenticator (OATH) authentication module to the authentication chain as follows:

      • Click Add a Module.

        The New Module dialog box appears.

      • Fill in the New Module dialog box, specifying the ForgeRock Authenticator (OATH) authentication module that you just created. For this example, specify the Requisite flag.

      • Click OK.

        The graphic showing your authentication chain now includes the Data Store and ForgeRock Authenticator (OATH) authentication module.

        An authentication chain setup for OATH authentication.
    • Save your changes.

  5. Test your authentication chain as follows:

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

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

    • Follow the procedure described in To Perform Authentication using a One-Time Password to verify that you can use the ForgeRock Authenticator app to perform multi-factor authentication. If the chain is correctly configured, authentication is successful and AM displays the user profile page.

To Perform Authentication using a One-Time Password

This example uses the authentication chain as created in Creating Chains for One-Time Password Authentication.

Because the first module in the authentication chain is a Data Store module, AM presents you with a page for entering your user ID and password. After you provide those credentials, AM verifies them. If your credentials are valid, AM proceeds to the ForgeRock Authenticator (OATH) authentication module.

On the ForgeRock Authenticator (OATH) screen, follow these steps to complete one-time password authentication:

  1. On your registered device, open the ForgeRock Authenticator app, and then tap the account matching the user ID you entered earlier.

    The registered authentication methods for that account are displayed:

    Supported authentication methods are displayed in each account. This account supports one-time passwords and push notifications.
  2. In the One-time Password section, click the refresh icon.

    A one-time password is displayed:

    Click the refresh icon to obtain new one-time passwords.
  3. On the ForgeRock Authenticator (OATH) page in AM, enter the one-time password that the authenticator app generated on your phone, and then click Submit:

    This is the page that AM uses to prompt you to enter a one-time password.

    AM will display the user’s profile page.

Letting Users Opt Out of One-Time Password Authentication (OATH)

Letting users opt out of providing one-time passwords when they perform multi-factor authentication is an important implementation decision. The Two Factor Authentication Mandatory setting under Realms > Realm Name > Authentication > Settings > General configures whether users can opt out.

When the Two Factor Authentication Mandatory setting is enabled, users must provide a one-time password every time they authenticate to a chain that includes a ForgeRock Authenticator (OATH) authentication module. When the setting is disabled, the user can optionally skip one-time passwords.

By default, AM lets users opt out of providing one-time passwords. Users authenticating with one-time passwords for the first time are prompted with a screen that lets them opt out of providing one-time passwords.

With the Two Factor Authentication Mandatory setting enabled, the user experience differs from the default behavior. AM does not provide an option to skip multi-factor authentication during the initial attempt at multi-factor authentication:

This is the screen you see the first time you authenticate using the Two Step Verification authentication module if you have not previously registered a device and if multi-factor authentication is mandatory. Notice that there is no option to skip multi-factor authentication.

When configuring an authentication chain that implements one-time passwords, you need to be aware that a user’s decision to opt out affects the authentication process. When a user who has opted out of providing one-time passwords authenticates to a chain that includes a ForgeRock Authenticator (OATH) authentication module, that module always passes authentication.

Consider the example authentication chain in Creating Chains for One-Time Password Authentication. The first authentication module is a Data Store module and the second authentication module is a ForgeRock Authenticator (OATH) module. Both authentication modules have the Requisite flag setting.

A user who has opted out of providing one-time passwords might experience the following sequence of events when authenticating to the chain:

  1. The Data Store authentication module prompts the user to provide a user ID and password.

  2. The user provides a valid user ID and password.

  3. Data Store authentication passes, and authentication proceeds to the next module in the chain—the ForgeRock Authenticator (OATH) module.

  4. The ForgeRock Authenticator (OATH) authentication module determines that the user has opted out of providing one-time passwords.

  5. ForgeRock Authenticator (OATH) authentication passes. Because it is the last authentication module in the chain, AM considers authentication to have completed successfully.

Contrast the preceding sequence of events to the experience of a user who has not opted out of providing one-time passwords, or who is required to provide one-time passwords, while authenticating to the same chain:

  1. The Data Store authentication module prompts the user to provide a user ID and password.

  2. The user provides a valid user ID and password.

  3. Data Store authentication passes, and authentication proceeds to the next module in the chain—the ForgeRock Authenticator (OATH) module.

  4. The ForgeRock Authenticator (OATH) authentication module determines that the user has not opted out of providing one-time passwords, and prompts the user for a one-time password.

  5. The user obtains a one-time password from the authenticator app on their mobile phone.

  6. If the one-time password is valid, ForgeRock Authenticator (OATH) authentication passes. Because it is the last authentication module in the chain, AM considers authentication to have completed successfully. However, if the one-time password is not valid, ForgeRock Authenticator (OATH) authentication fails, and AM considers authentication to have failed.

Opting Out of One-Time Password Authentication (OATH)

Unless the AM administrator has made one-time password authentication mandatory, users can choose to opt out of using one-time passwords by clicking the Skip This Step button on the ForgeRock Authenticator (OATH) screen. (For information about making the usage of one-time passwords mandatory in AM, see Letting Users Opt Out of One-Time Password Authentication (OATH).) This button appears:

  • When users are prompted to register their mobile devices during their initial login from a new device.

  • Every time users are prompted by the ForgeRock Authenticator (OATH) authentication module to enter one-time passwords.

Users who decide to opt out of using one-time passwords are not prompted to enter one-time passwords when authenticating to AM.

The decision to opt out of using one-time passwords in AM is revocable: users who have decided to opt out of using one-time passwords can reverse their decisions, so that one-time password authentication is once again required.

End users should follow these steps to opt out or opt in to using one-time passwords:

To Opt out or Opt in to Using One-Time Passwords

  1. Log in to AM.

  2. Select Dashboard from the top navigation bar.

  3. In the Authentication Devices section of the Dashboard page, click the context menu button for the chosen device, and then click Settings:

    This is the menu that appears in the AM dashboard for authentication devices.
  4. Enable or disable the multi-factor authentication option:

    This is the form that lets you set one-time password options in AM. The option to perform one-time password authentication can be toggled if not configured to be mandatory by the administrator.
  5. Click Save.