MFA: Use codes from ForgeRock app using OATH

The ForgeRock Authenticator (OATH) nodes support HMAC one-time password (HOTP) and time-based one-time password (TOTP) authentication as defined in the OATH standard protocols for HOTP (RFC 4226) and TOTP (RFC 6238). Both HOTP and TOTP authentication require an OATH-compliant device that can provide the password.

About one-time password support

HOTP authentication generates the one-time password (OTP) every time the user requests a new password on their device. The device tracks the number of times the user requests a new one-time password with a counter. The one-time password displays for a period of time you designate in the setup, so the user may be further in the counter on their device than on their account.

Identity Cloud resynchronizes the counter when the user finally logs in. To accommodate this, you set the number of passwords a user can generate before their device cannot be resynchronized. For example, if you set the number of HOTP Window Size to 50 and someone presses the button 30 times on the user’s device to generate a new password, the counter in Identity Cloud will review the passwords until it reaches the one-time password entered by the user. If someone presses the button 51 times, you will need to reset the counter to match the number on the device’s counter before the user can log in to Identity Cloud. HOTP authentication does not check earlier passwords, so if the user attempts to reset the counter on their device, they will not be able to log in until you reset the counter in Identity Cloud to match their device. For more information, refer to Reset registered devices using REST.

TOTP authentication constantly generates a new one-time password based on a time interval you specify. The device tracks the last several passwords generated and the current password. The TOTP Time Steps setting configures the number of passwords tracked. The Last Login Time setting monitors the time when a user logs in to make sure that user is not logged in several times within the present time period. The TOTP Time-Step Interval should not be so long as to lock users out, with a recommended time of 30 seconds.

Create a journey for one-time password authentication

The following example journey uses TOTP, the default:

In the Identity Cloud admin UI, start a custom OATH journey.

For details, refer to Custom journeys.
In the Identity Cloud admin UI, add the following nodes to your journey:
- Data Store Decision node
- Page node
- Platform Password node
- Platform Username node
- OATH Token Verifier node (use two copies of this node)
- OATH Registration node
- OATH Device Storage node
- Recovery Code Collector Decision node
- Recovery Code Display node
- Retry Limit Decision node
On the first OATH Token Verifier node, select Allow recovery codes.
On the OATH Registration node, select Generate Recovery Codes.

The value for OATH Algorithm must be the same for the registration and verification nodes.
Connect the nodes as shown:
Save your changes.

This journey demonstrates OATH authentication. In a production environment, you could include additional nodes, such as:

Get Authenticator App node: Displays links to the ForgeRock Authenticator app for Android and iOS.
MFA Registration Options node: Provides options for users to register a multi-factor authentication device, get the authenticator app, or skip the registration process.
Opt-out Multi-Factor Authentication node: Sets an attribute in the user’s profile which lets them skip multi-factor authentication.

Authenticate using a one-time password

After creating the journey, try it:

Register a test user account unless you have already done so.
In an incognito browser window, browse to the journey. The URL looks something like:
```
https://<tenant-env-fqdn>/am/XUI/?realm=alpha&authIndexType=service&authIndexValue=myOathTotpJourney
```
A login screen prompts for your credentials.
Sign in with the username and password of the test user.

A registration screen prompts to display a QR code.
Register an authenticator, such as the ForgeRock Authenticator app, by scanning the QR code.

The journey registers your one-time password app and displays recovery codes.
Save the recovery codes and click Done to proceed to one-time password authentication.
Enter the one-time password from your app, and click Submit:

If the animated timer indicates the one-time password is close to expiry, wait for the app to generate a new one.

The UI displays the user profile page.
Browse to Edit Your Profile > 2-Step Verification > Change.

The UI displays your registered devices.

The one-time password app you registered is named OATH Device.