--- title: OATH Token Verifier node description: The OATH Token Verifier node requests and verifies a one-time passcode (OTP) generated by a device such as a mobile phone. component: auth-node-ref version: latest page_id: auth-node-ref::oath-token-verifier canonical_url: https://docs.pingidentity.com/auth-node-ref/latest/oath-token-verifier.html keywords: ["Nodes & Trees", "Journeys", "Authentication", "OAuth 2.0", "HMAC", "Multi-factor Authentication (MFA)"] page_aliases: ["auth-node-oath-token-verifier.adoc"] superseded_by: https://docs.pingidentity.com/auth-node-ref/latest/oath-token-verifier.html section_ids: authn-mfa-oath-tree-example: Example availability: Availability authenticators: Authenticators inputs: Inputs dependencies: Dependencies configuration: Configuration outputs: Outputs callbacks: Callbacks outcomes: Outcomes errors: Errors --- # 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](oath-registration.html). | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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: ![OATH journey with device registration](_images/oath-journey.png) * The [Page node](page.html) with the [Platform Username node](platform-username.html) and the [Platform Password node](platform-password.html) prompts for the user credentials. * The [Data Store Decision node](data-store-decision.html) confirms the username-password credentials. * The first [OATH Token Verifier node](oath-token-verifier.html) prompts for a one-time passcode with an option to use a recovery code. * The [OATH Registration node](oath-registration.html) prompts the user to register a device and includes its profile in the shared state. * The [Recovery Code Display node](recovery-code-display.html) shows the recovery codes and prompts the user to keep them safe. * The second [OATH Token Verifier node](oath-token-verifier.html) prompts for a one-time passcode using the newly registered device. * The [OATH Device Storage node](oath-device-storage.html) writes the device profile to the user's account. * The [Recovery Code Collector Decision node](recovery-code-collector-decision.html) prompts for a recovery code. * The [Retry Limit Decision node](retry-limit-decision.html) 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 | ### Authenticators The OATH-related nodes can integrate with the following authenticator apps: * [PingID mobile app](https://docs.pingidentity.com/pingid-user-guide/pid_mobile_app/ug_pid_mobile_app_for_ios_and_android.html) * [ForgeRock Authenticator](https://docs.pingidentity.com/sdks/latest/authenticator/index.html) app * Third-party authenticator apps that support the following open standards: * [RFC 4226](https://tools.ietf.org/html/rfc4226): HMAC-Based One-Time Password (HOTP) * [RFC 6238](https://tools.ietf.org/html/rfc6238): Time-Based One-Time Password (TOTP) ## Inputs This node reads the `username` attribute from the shared state. Implement a [Platform Username node](platform-username.html) earlier in the journey. ## Dependencies Confirm the user credentials before letting them authenticate with a device. Implement a [Platform Username node](platform-username.html) and a [Platform Password node](platform-password.html) earlier in the journey. Also implement a [Data Store Decision node](data-store-decision.html) ## 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](oath-registration.html). - 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](https://docs.pingidentity.com/pingoneaic/am-authentication/authn-mfa-using-out-of-sync.html).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. Learn more in [Supported callbacks](https://docs.pingidentity.com/pingoneaic/am-authentication/callbacks-supported.html). ## 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.