Advanced Identity Cloud

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

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

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:

OATH journey with device registration