AM 7.2.2

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 (OTP) 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 Reset registered devices over 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 between authentication modules that support HOTP

AM provides two authentication modules that support OATH:

  • The ForgeRock Authenticator (OATH) authentication module, which is optimized for use with the ForgeRock Authenticator app and provides device profile encryption.

  • The OATH authentication module, which is a raw OATH implementation requiring more configuration for users and the AM administrator.

We recommend using the ForgeRock Authenticator (OATH) authentication module when possible.

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

✔

✔

One-time password authentication using trees

This section describes how to create and configure trees for one-time password authentication.

Create a tree for one-time password authentication

To create an example authentication tree that uses OATH authentication, perform the following steps:

  1. In the AM admin UI, select the realm that will contain the authentication tree.

  2. Select Authentication > Trees, and click +Create Tree.

  3. Type a name for your tree in the New Tree page; for example, myAuthTree, and click Create.

    The authentication tree designer page is displayed with default Start, Failure, and Success nodes.

    For information about using the authentication tree designer, see Create an authentication tree.

  4. Add the following nodes to the designer area:

  5. Connect the nodes as shown:

    Connect the nodes to gather user credentials.

  6. Type 'OATH' to filter the list of nodes in the Components panel box:

  7. Drag an OATH Token Verifier node and an OATH Registration node onto the designer area.

  8. For both OATH nodes, set the OATH Algorithm property to TOTP, and connect to the existing nodes as follows:

    The OATH authentication tree.

    The value for OATH Algorithm must be the same for both nodes. For this example, select TOTP to generate a new OTP at a specified time step interval.

  9. Save your changes.

    Note that the tree you have created is a simple example for the purposes of demonstrating a basic OATH authentication journey. In a production environment, you could include additional nodes, such as:

    MFA Registration Options node

    Provides options for users to register a multi-factor authentication device, get the authenticator app, or skip the registration process.

    Opt-out Multi-Factor Authentication node

    Sets an attribute in the user’s profile which lets them skip multi-factor authentication.

    Recovery Code Display node

    Lets a user to view recovery codes to use in case they have lost or damaged their registered authenticator device.

    Retry Limit Decision node

    Lets a journey loop a specified number of times, for example, to allow a user to retry entering their OATH token.

    For information about how to configure these nodes, see Authentication nodes configuration reference.

  10. Test your authentication tree as follows:

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

    • Log in using the username and password. For example, enter demo, and the password Ch4ng31t.

    • On successful login, if the screen displays a QR code, you will need to register your device.

      To register the device with the ForgeRock Authenticator, follow the instructions as described in Register the ForgeRock Authenticator for MFA.

    • Follow the procedure described in Authenticate with a one-time password to verify that you can authenticate using the ForgeRock Authenticator app.

Authenticate with a one-time password

This example task assumes the following prerequisites:

Follow these steps to complete one-time password (OTP) authentication:

  1. On your registered device, open the ForgeRock Authenticator app, and then tap the OTP section for the account matching the user ID. For example:

    The account for the demo user.

  2. Note the OTP that is displayed on the screen. This is automatically refreshed at an interval defined in the OATH node configuration. If the animated timer indicates the OTP is close to expiry, wait until a new OTP is generated.

  3. On the ForgeRock Authenticator (OATH) page in AM, enter the OTP that the authenticator app generated on your phone, and click Submit:

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

    AM displays the user’s profile page.

One-time password authentication using chains

This section covers one-time password authentication.

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.

See Authentication modules and chains for details about authentication module flag settings.

  • 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 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 Let users opt out of one-time password authentication (OATH).

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

    • Select Authentication > Modules, and click Add Module.

    • Complete the New Module page as follows:

      • Name: Specify a module name.

      • Type: Select ForgeRock Authenticator (OATH).

    • Click Create.

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

      For more information about the authentication module’s configuration settings, see ForgeRock Authenticator (OATH) Authentication Module.

  4. Create the authentication chain as follows:

    • Go to Authentication > Chains, and click Add Chain.

    • Specify a name, for example myOATHAuthChain, and click Create.

    • Click Add a Module. Complete 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.

        See Authentication modules and chains for information about authentication module flag settings.

    • Click OK.

      A graphic showing an authentication chain with a single Data Store module is displayed.

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

      • Click Add a Module.

      • 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 go to a URL similar to the following: https://openam.example.com:8443/openam/XUI/?realm=/&service=myOATHAuthChain#login

    • Follow the procedure described in Authenticate with 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.

Authenticate with a one-time password

This example uses the authentication chain as created in One-time password authentication using chains.

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

Let 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 One-time password authentication using chains. 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.

Opt 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 Let 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:

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 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. Save your work.

Copyright © 2010-2024 ForgeRock, all rights reserved.