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
andTOTP
: -
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.
}
});