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:

Identifies the user by requesting credentials and verifying them with a Data Store Decision node.
Registers a device, if the user has not already done so, by using an OATH Registration node.
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

Create a new authentication tree in AM or Identity Cloud, with a suitable name; for example, OATH.
To identify the user, obtain their credentials in a Page Node connected to a Data Store Decision node:

In Identity Cloud, use the Platform Username and Platform Password nodes to obtain the users' credentials.
Add an OATH Token Verifier node.

In the OATH Algorithm property, choose between HOTP and TOTP:
Connect an OATH Registration node.

In the OATH Algorithm property, select the same value as the OATH Token Verifier node from the previous step:
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:

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>() {

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

    @Override
    public void onFailure(final MechanismCreationException e) {
        // called when device enrollment has failed.
    }
});

ForgeRock SDKs

Add one-time password (OATH) support

Prepare AM for OATH

Create an example journey

Register your application for OATH