OATH Token Verifier node

The OATH Token Verifier node requests and verifies a one-time passcode (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 an authenticator app to register your device, receive notifications, and generate one-time passwords.

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.

Availability

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

Product

Available?

PingOne 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:

PingID mobile app
ForgeRock Authenticator app
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.

Implement a Platform Username node and a Platform Password node earlier in the journey.

Also implement a Data Store Decision node

Configuration

Property Usage

OATH Algorithm

Select the algorithm the device uses to generate the OTP.

Possible values are:

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

The amount the OTP device and 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

The number of time steps that 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 2, the server accepts the two previous codes, the code generated for the current time step, and the next two codes.

Default: 2

TOTP Hash Algorithm

The HMAC hash algorithm used to generate the OTP codes.

Possible values are:

HMAC-SHA1
HMAC-SHA256
HMAC-SHA512

Changing this algorithm invalidates all existing OATH device registrations. You must reset OATH devices before users can re-register their devices under the new algorithm. For example, you could use a Scripted Decision node to remove the current device, followed by an OATH Registration node to register it again.

Default: HMAC-SHA1

TOTP Maximum Allowed Clock Drift

The number of time steps that the authenticator app can be out of sync with the server before manual resynchronization is required. Learn more about manual resynchronization in Recover after a device becomes out of sync.

For example, with the default TOTP Time Steps of 2 and the TOTP Time Step Interval of 30 seconds, the server treats codes up to 60 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

Select this option to let users provide a recovery code to authenticate.

Default: Not enabled

Outputs

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

Callbacks

The node sends the following callbacks:

ConfirmationCallback: Lets the user submit their OTP or choose to provide a recovery code.
NameCallback: Prompts the user to enter the OTP code generated by their device.

Outcomes

Success: The user has a registered device and the token code was verified.
Failure: The user wasn’t 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 can’t 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.

Authentication nodes