PingOne Advanced Identity Cloud

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.

Advanced 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 HOTP Window Size to 50 and the user presses the button 30 times on their device to generate a new password, the counter in Advanced Identity Cloud reviews the passwords until it reaches the one-time password entered by the user. If the user 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 Advanced Identity Cloud. HOTP authentication does not check earlier passwords, so if the user attempts to reset the counter on their device, they won’t be able to log in until you reset the counter in Advanced 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:

  1. In the Advanced Identity Cloud admin console, start a custom OATH journey.

    Learn more in Custom journeys.

  2. In the Advanced Identity Cloud admin console, add the following nodes to your journey:

  3. On the first OATH Token Verifier node, select Allow recovery codes.

  4. On the OATH Registration node, select Generate Recovery Codes.

    The value for OATH Algorithm must be the same for the registration and verification nodes.

  5. Connect the nodes as shown:

    Connect the nodes to gather user credentials.

  6. 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, test it as follows:

  1. Register a test user account unless you have already done so.

  2. Copy and paste the Preview URL into a browser in incognito mode.

    A login screen prompts for your credentials.

  3. Sign in with the username and password of the test user.

    A registration screen prompts to display a QR code.

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

  5. Save the recovery codes and click Done to proceed to one-time password authentication.

  6. Enter the one-time password from your app, and click Submit:

    The prompt to enter a one-time password.

    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.

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