OATH Token Verifier node

The OATH Token Verifier node requests and verifies a one-time password (OTP) generated by a device such as a mobile phone.

The default configuration is time-based OTP (TOTP), but the node also supports HMAC (HOTP).

The node requires prior authentication and a device registered with an OATH Registration node.

You can use the OATH nodes in conjunction with the ForgeRock Authenticator application to register your device, receive notifications, and generate one-time passwords.

Compatibility

Product	Compatible?
Advanced Identity Cloud	Yes
PingAM (self-managed)	Yes
Ping Identity Platform (self-managed)	Yes

Product

Compatible?

Advanced Identity Cloud

Yes

PingAM (self-managed)

Yes

Ping Identity Platform (self-managed)

Yes

Authenticators

The OATH-related nodes can integrate with the following authenticator apps:

The ForgeRock Authenticator app for Android and iOS.
Third-party authenticator apps that support the following open standards:
- RFC 4226: HMAC-Based One-Time Password (HOTP)
- RFC 6238: Time-Based One-Time Password (TOTP)

Inputs

This node reads the username attribute from the shared state.

Dependencies

Confirm the user credentials before letting them authenticate with a device. For example, precede this node with the following nodes earlier in the authentication flow:

Configuration

Property Usage

Property	Usage
OATH Algorithm	Specify the algorithm the device uses to generate the OTP: HOTP HOTP uses a counter; the counter increments every time a new OTP is generated. When you use this setting, also set the same value in the OATH Registration node. TOTP TOTP generates a new OTP every few seconds as specified by the TOTP Time Step Interval setting. Default: `TOTP`
HOTP Window Size	Specify how much the OTP device and the server counter can be out of sync. For example, if the window size is 100 and the server’s last successful login was at counter value 2, the server accepts an OTP that is generated between counter 3 and 102. Default: `100`
TOTP Time Step Interval	The length of time an OTP is valid in seconds. For example, if the time step interval is 30 seconds, a new OTP is generated every 30 seconds and is valid for 30 seconds only. Default: `30` seconds
TOTP Time Steps	Specify how many time steps the OTP can be out of sync. This applies to codes generated before or after the current code. For example, with a time step of 1, the server accepts the previous, current, and next codes. Default: `2`
TOTP Hash Algorithm	The HMAC hash algorithm used to generate the OTP codes. The ForgeRock Authenticator application supports SHA1, SHA256, and SHA512. Default: `SHA1`
TOTP Maximum Allowed Clock Drift	Specify how many time steps the authenticator application can be out of sync with the server before manual resynchronization is required. For example, with TOTP Time Steps of `3` and a TOTP Time Step Interval of 30 (seconds), the server treats codes up to 90 seconds from the current time as belonging to the current time step. The drift for a user’s device is calculated each time they enter a new code. If the drift exceeds this value, the outcome is `Failure`. Default: `5`
Allow recovery codes	If enabled, lets users provide a recovery code to authenticate. Default: false

OATH Algorithm

Specify the algorithm the device uses to generate the OTP:

HOTP: HOTP uses a counter; the counter increments every time a new OTP is generated. When you use this setting, also set the same value in the OATH Registration node.
TOTP: TOTP generates a new OTP every few seconds as specified by the TOTP Time Step Interval setting.

Default: TOTP

HOTP Window Size

Specify how much the OTP device and the server counter can be out of sync.

For example, if the window size is 100 and the server’s last successful login was at counter value 2, the server accepts an OTP that is generated between counter 3 and 102.

Default: 100

TOTP Time Step Interval

The length of time an OTP is valid in seconds.

For example, if the time step interval is 30 seconds, a new OTP is generated every 30 seconds and is valid for 30 seconds only.

Default: 30 seconds

TOTP Time Steps

Specify how many time steps the OTP can be out of sync.

This applies to codes generated before or after the current code. For example, with a time step of 1, the server accepts the previous, current, and next codes.

Default: 2

TOTP Hash Algorithm

The HMAC hash algorithm used to generate the OTP codes. The ForgeRock Authenticator application supports SHA1, SHA256, and SHA512.

Default: SHA1

TOTP Maximum Allowed Clock Drift

Specify how many time steps the authenticator application can be out of sync with the server before manual resynchronization is required.

For example, with TOTP Time Steps of 3 and a TOTP Time Step Interval of 30 (seconds), the server treats codes up to 90 seconds from the current time as belonging to the current time step.

The drift for a user’s device is calculated each time they enter a new code. If the drift exceeds this value, the outcome is Failure.

Default: 5

Allow recovery codes

If enabled, lets users provide a recovery code to authenticate.

Default: false

Outputs

If the outcome is Not registered, this node sets "mfaMethod": "oath" in the shared state

Outcomes

Success: The user has a registered device and the token code was verified.
Failure: The user was not authenticated, or the collected token code can’t be verified.
Not registered: The user account has no registered device profiles.
Recovery Code: Allow recovery codes is enabled, and the user chose to provide a recovery code.

Errors

If this node cannot read the username from the shared state, it logs an error message: Expected username to be set.

If processing raises an exception, this node logs the detail as an error message.

Example

The following journey includes both username-password and one-time passcode authentication:

The Page node with the Platform Username node and the Platform Password node prompts for the user credentials.
The Data Store Decision node confirms the username-password credentials.
The first OATH Token Verifier node prompts for a one-time passcode with an option to use a recovery code.
The OATH Registration node prompts the user to register a device and includes its profile in the shared state.
The Recovery Code Display node shows the recovery codes and prompts the user to keep them safe.
The second OATH Token Verifier node prompts for a one-time passcode using the newly registered device.
The OATH Device Storage node writes the device profile to the user’s account.
The Recovery Code Collector Decision node prompts for a recovery code.
The Retry Limit Decision node lets the user retry another code if they enter one incorrectly.