ForgeRock Developer Experience

Implement MFA using OATH one-time passwords

Applies to:

  • ForgeRock SDK for Android

  • ForgeRock SDK for iOS

  • ForgeRock SDK for JavaScript

In this use case you configure your ForgeRock server to require a single-use, one-time password generated by the ForgeRock Authenticator when users authenticate.

Overview

The ForgeRock Authenticator supports one-time password (OTP) authentication as defined in the OATH standard protocols.

The following methods for generating one-time passwords are supported:

HMAC-based one-time passwords (HOTP)

As described in RFC 4226, 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 user may be further in the counter on their device than the server.

Your ForgeRock server resynchronizes 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 HOTP Window Size to 50 and someone presses the button 30 times in the ForgeRock Authenticator to generate a new password, the counter in your ForgeRock server will review the passwords until it reaches the one-time password entered by the user.

If, however, 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.

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 on the server to match their device.

Time-based one-time passwords (TOTP)

As described in (RFC 6238), TOTP authentication constantly generates a new one-time password based on a time interval you specify.

The TOTP Time Step Interval setting configures how often a new password is generated by the ForgeRock Authenticator.

Use the TOTP Time Steps setting to provide a margin in case the time varies between your ForgeRock server and the device running the ForgeRock Authenticator. For example, set this to 1 to accept either the previous, the current, or the next password as valid.

Step 1. Create an OATH registration and authentication journey

In this step you create an authentication journey that registers a device running the ForgeRock Authenticator to the user’s profile if they have not done so already, then requests a one-time password from the device.

Choose whether you are creating the journey in Identity Cloud or a self-managed AM server, and follow the instructions to create the required authentication journey:

  • Identity Cloud

  • Self-managed AM server

  1. In the Identity Cloud admin UI

    1. Select the realm that will contain the authentication journey.

    2. Select Journeys, and click New Journey.

    3. Enter a name for your tree in Name page; for example, MFAwithOATH

    4. In Identity Object, select the identity type that will be authenticating, for example group Alpha realm - Users.

    5. Click Save.

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

  2. Add the following nodes to the designer area:

  3. Connect the nodes as shown:

    Connect the nodes to identify the user, then verify their OATH token.
    Figure 1. Connect the nodes to identify the user, then verify their OATH token.

  4. Ensure that the OATH Token Verifier node and the OATH Registration node or Combined MFA Registration node are using the same value for OATH Algorithm.

    In this example, select TOTP.

  5. Save your changes.

  1. In the AM admin UI:

    1. Select the realm that will contain the authentication tree.

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

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

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

  2. Add the following nodes to the designer area:

  3. Connect the nodes as shown:

    Connect the nodes to identify the user, then verify their OATH token.
    Figure 2. Connect the nodes to identify the user, then verify their OATH token.

  4. Ensure that the OATH Token Verifier node and the OATH Registration node or Combined MFA Registration node are using the same value for OATH Algorithm.

    In this example, select TOTP.

  5. Save your changes.

The tree you create 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:

Get Authenticator App node

Provides links to download the official ForgeRock Authenticator for Android and iOS.

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 lose or damage the authenticator device they register.

Recovery Code Collector Decision node

Lets a user enter their recovery codes to authenticate 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.

Step 2. Authenticate using a one-time password

After creating the journey, you can register the ForgeRock Authenticator, and use it to generate and authenticate with a single-use, one-time password:

  1. If you have not already done so, create a demo user in your server:

  2. In an incognito browser window, browse to the journey you created in the previous step:

    Identity Cloud

    https://openam-forgerock-sdks.forgeblocks.com/am/XUI/?realm=alpha&authIndexType=service&authIndexValue=MFAwithOATH

    Self-managed AM server

    https://openam.example.com:8443/openam/XUI/?realm=alpha&authIndexType=service&authIndexValue=MFAwithOATH

    The journey asks for your credentials:

    Enter the credentials of your demo account.

  3. Sign in with the username and password of your demo user.

    If you have not yet registered the ForgeRock Authenticator, the journey displays a QR code:

    Register the Authenticator using the QR code.

  4. In the ForgeRock Authenticator, click the blue plus icon to register the account on the device:

    Click the plus icon to add an account in the Authenticator.

  5. In the Add Account menu that appears, select Scan QR Code:

    From the menu, select the Scan QR code option.

  6. Scan the QR code on screen using the ForgeRock Authenticator:

    Scan the QR code using the Authenticator.

  7. When the ForgeRock Authenticator registers the account, in your browser, click Next to continue the journey.

    The journey requests the one-time password:

    journey idcloud oath verify en

  8. Enter the verification code from the ForgeRock Authenticator.

    Enter the code the Authenticator displays for the account.

    If the animated timer indicates the one-time password is close to expiry, wait for the app to generate a new one.

    If you enter a valid one-time password, the browser displays the user’s profile page.

Next steps

You can add support for MFA using one-time passwords to your own Android and iOS applications, by using the ForgeRock Authenticator module.

For more information, refer to Integrate MFA using OATH one-time passwords.

1. Use the combined MFA registration node if you intend to add Push notifications as an MFA method.
Copyright © 2010-2024 ForgeRock, all rights reserved.