AM 7.3.1

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.

About one-time password support

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 log in 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 log in until you reset the counter in AM to match their device. For more information, refer to 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.

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 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 in The ForgeRock Authenticator application.

    • 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:

    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 Token Verifier node. 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.

Copyright © 2010-2024 ForgeRock, all rights reserved.