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

Setup
, , , , ,
#1

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:

    uc_oath_journey
    uc_oath_journey2280×766 148 KB

    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

    uc_oath_verifier_node
    uc_oath_verifier_node282×737 42.9 KB

  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

    uc_oath_registration_node
    uc_oath_registration_node281×1053 63.5 KB

  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.

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

    uc_oath_asmith_sign_in

    A QR code is displayed for registering your device.

    uc_oath_QR
    uc_oath_QR422×588 61.2 KB

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

    uc_add_account

    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.

    uc_asmith_login_screen
    uc_asmith_login_screen2866×1284 118 KB

  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.

    uc_profile_2-step-verification
    uc_profile_2-step-verification944×320 36.1 KB

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

    uc_profile_2-step-verification_OATH

    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.

    uc_enter_v_code_complete

    You are successfully logged in as the test user.

Additional resources

Documentation:

Training videos:

1 Like
Implement MFA using Google Authenticator (TOTP)
A comprehensive approach to CIAM vendor selection
ForgeRock Identity Cloud: Preventing access for unknown users and bad actors
ForgeRock Identity Cloud: Validating a known user's identity