Use case: Configure OATH-based token two-factor authentication in ForgeRock Identity Cloud

Use case overview

Allowing two-factor authentication using hardware or software-based tokens based on OATH standards for strong authentication is a very common use case that is easily implemented in ForgeRock Identity Cloud.

ForgeRock provides built-in support for HMAC one-time passcode (HOTP) and time-based one-time passcode (TOTP) as authentication and authorization methods. These methods authenticate based on codes generated using a secret shared previously by the ForgeRock server and an OATH-compliant device. Users can register their devices, using a QR code, to generate OTPs which can be used to securely log in.

This simple use case demonstrates how to build a user journey in Identity Cloud that prompts the user to authenticate with TOTP for second-factor authentication. It uses the ForgeRock Authenticator app, which is available for iOS and Android devices and can be downloaded from the Apple App Store or Google Play.

NOTE: ForgeRock also supports a number of third-party OATH-compliant authenticators, including Google Authenticator and Yubico’s YubiKey devices.

Steps to achieve this use case

To create a simple OATH authentication journey:

  1. Sign in to the Identity Cloud admin UI using your admin tenant URL, in the format https://<tenant-name>/am/XUI/?realm=/#/.

  2. Go to Journeys > New Journey.

  3. Enter a unique name for the OATH journey, select which identities will authenticate using this journey, (optionally) enter a journey description, and click Save.

  4. Create a journey similar to this:

    Node descriptions:

    • Platform Username - Prompts the user to enter their username. See Platform Username node for further information.
    • Platform Password - Collects the user’s password. See Platform Password node for more information.
    • Data Store Decision - Verifies that the username and password values match those in the data store configured for the realm. See Data Store Decision node for further information.
    • OATH Token Verifier - Requests and verifies a one-time password (OTP) generated by a device such as a mobile phone. See OATH Token Verifier node for further information.
    • OATH Registration - Lets the user register a device for OATH-based multi-factor authentication (MFA). See OATH Registration node for further information.
  5. Click on the OATH Token Verifier node and confirm the following:

    • OATH Algorithm is set to TOTP
    • TOTP Hash Algorithm is set to HMAC-SHA256

  6. Click on the OATH Registration node and confirm the following:

    • Minimum Secret Key Length is set to 40
    • OATH Algorithm set to TOTP
    • TOTP Hash Algorithm is set to HMAC-SHA256

  7. Click Save to save the journey.

NOTE: This simple journey doen’t include a recovery code step in case of lost or stolen devices. For information on adding this step, see Configure lost second-factor token replacement in ForgeRock Identity Cloud.

Testing the use case

To test the use case, you’ll need an OATH-enabled device with the ForgeRock Authenticator app installed. You can download the app from the Apple App Store or Google Play.

Make sure that your test end user doesn’t have the device already registered on their profile.

Register a new device

  1. In the Identity Cloud admin UI, go to Journeys.

  2. Click the OATH journey you created in the previous steps and copy the Preview URL.


  3. Paste the preview URL into a browser using Incognito or Browsing mode.

  4. Enter the test user’s username and password and click Next.


    A QR code is displayed for registering your device.

  5. On your mobile device:
    a. Open the ForgeRock Authenticator app on your device and tap +.
    b. Click Scan QR Code.


    c. Scan the QR code.

  6. Click Next.

    Once your identity has been verified and the device has been associated with the account, you are successfully logged in as the test user.

  7. Click Edit Your Profile.

    In the Sign-in & Security section, 2-Step Verification should be ‘On’. This indicates that device(s) have been registered.

  8. Click Change to verify that the OATH device has been registered.


    NOTE: If the user logs in using the OATH device they can delete the device from their profile.

  9. Sign out of Identity Cloud.

Sign in using the registered device

  1. Paste the same OATH journey URL (you created previously) into a browser using Incognito or Browsing mode.

  2. Enter the test user’s username and password and click Next.

  3. On the registered device, open the ForgeRock authentication app to display the 6 digit verification code.

  4. Enter the verification code in the Identity Cloud sign in screen and click Submit.


    You are successfully logged in as the test user.

Additional resources


Training videos:

1 Like