ForgeRock SDKs

Add one-time password (OATH) support

This section covers how to add support for one-time passwords for second-factor authentication.

Prepare AM for OATH

This section covers how to configure AM with an authentication journey (tree) suitable for registering a device, and performing OATH-based multi-factor authentication.

The authentication journey performs the following tasks:

  1. Identifies the user by requesting credentials and verifying them with a Data Store Decision node.

  2. Registers a device, if the user has not already done so, by using an OATH Registration node.

  3. Requests, and verifies an OATH token, by using the OATH Token Verifier node.

For simplicity, the example journey in this section provides the shortest journey possible for OATH authentication. In a production environment, you could include additional nodes in the authentication journey, such as:

MFA Registration Options

Provides paths for users to get the ForgeRock Authenticator, or to skip or opt-out of MFA.

Recovery Code Display and Collector

Lets a user authenticate with a recovery code when they lose or damage their registered authenticator device.

Retry Limit Decision

Lets a journey loop a specified number of times. For example, the journey can let a user retry entering their OATH token.

Create an example journey

  1. Create a new authentication tree in AM or Identity Cloud, with a suitable name; for example, OATH.

  2. To identify the user, obtain their credentials in a Page Node connected to a Data Store Decision node:

    Identify the user

    In Identity Cloud, use the Platform Username and Platform Password nodes to obtain the users' credentials.

  3. Add an OATH Token Verifier node.

    In the OATH Algorithm property, choose between HOTP and TOTP:

    Request and verify the token
  4. Connect an OATH Registration node.

    In the OATH Algorithm property, select the same value as the OATH Token Verifier node from the previous step:

    Register a device
  5. Save your changes.

Register your application for OATH

The first time you authenticate to your authentication tree, you are asked to register a device by scanning a QR code.

Your application must implement a QR code scanning mechanism:

Registering an identity in Android

You can find an example in the sample authenticator application provided in the forgerock-android-sdk repository.

After you scan the QR code and obtain the URI, register the OATH mechanism by implementing the FRAClient.createMechanismFromUri() method. The FRAListener can be used to receive the newly created mechanism:

fraClient.createMechanismFromUri("qrcode_scan_result", new FRAListener<Mechanism>() {

    public void onSuccess(Mechanism mechanism) {
        // called when device enrollment was successful.

    public void onFailure(final MechanismCreationException e) {
        // called when device enrollment has failed.
Copyright © 2010-2023 ForgeRock, all rights reserved.