--- title: OATH Registration node description: The OATH Registration node lets the user register a device for OATH-based multi-factor authentication (MFA). Learn more about OATH in the OATH documentation. component: auth-node-ref version: latest page_id: auth-node-ref::oath-registration canonical_url: https://docs.pingidentity.com/auth-node-ref/latest/oath-registration.html keywords: ["Nodes & Trees", "Journeys", "Authentication", "OAuth 2.0", "Registration", "Multi-factor Authentication (MFA)"] page_aliases: ["auth-node-oath-registration.adoc"] superseded_by: https://docs.pingidentity.com/auth-node-ref/latest/oath-registration.html section_ids: example: Example availability: Availability authenticators: Authenticators inputs: Inputs dependencies: Dependencies configuration: Configuration outputs: Outputs callbacks: Callbacks outcomes: Outcomes errors: Errors --- # OATH Registration node The OATH Registration node lets the user register a device for OATH-based multi-factor authentication (MFA). Learn more about OATH in the [OATH documentation](https://www.openauthentication.org/about.html). Based on the node settings, the user device displays a QR code that includes all the details required for registration. If registration is successful, the node stores the device data and recovery codes (if enabled), and sets the `skippable` attribute to prevent repeat registration at next login. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You can use the [Combined MFA Registration node](combined-mfa-registration.html) to register a device for both push notifications and one-time passcode (OATH) verification in a single step. | ## 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 and optionally the `oathDeviceProfile` 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 register 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 | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Issuer | The identifier that's displayed on the user's device, such as a company name, a website, or a realm.The authenticator app displays this value.Default: `ForgeRock` | | Account Name | Select the profile attribute to display as the username in the authenticator app.If not specified, or if the specified profile attribute is empty, their username is used.Default: `Username` | | Background Color | The background color in hex notation that displays behind the issuer's logo within the authenticator app.Default: `032b75` | | Logo Image URL | The location of an image to download and display as the issuer's logo within the authenticator app. PingID mobile app supports JPEG, JPG, GIF, or PNG files with a maximum size of 1 MB. Find more information in the PingID documentation. The ForgeRock Authenticator app supports logos in JPEG and PNG format only. The application resizes your logo automatically, but a maximum image size of one MByte (or 1024 X 1024 pixels) is recommended.Default: none | | Generate Recovery Codes | Select this option to generate and store recovery codes in the successful outcome's transient state.Use the [Recovery Code Display node](recovery-code-display.html) to display the codes to the user for safekeeping.Default: `Enabled` | | QR code message | A custom, localized message with instructions to scan the QR code to register the device.> **Collapse: Add instructions** > > 1. Click [icon: plus, set=fa]. > > 2. In the Key field, enter the locale. For example, `en-gb`.[(1)](#locale-footnote) > > 3. In the Value field, enter the message. > > 4. Click Done. > > 5. Repeat to add more messages and save your changes when you're done.Leave blank to use the default message.Default: none | | One Time Password Length | The length of the generated OTP in digits.This value must be at least `6`. It must also be compatible with the hardware/software OTP generators you expect end users to use. For example, Google and ForgeRock authenticators support values of `6` and `8` respectively.Default: `6` | | Minimum Secret Key Length | The number of hexadecimal characters allowed for the secret key.Default: `32` | | 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 Token Verifier node](oath-token-verifier.html). - TOTP TOTP generates a new OTP every few seconds as specified by the TOTP Time Step Interval setting.Default: `TOTP` | | TOTP Time Step Interval | The length of time that 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 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` | | HOTP Checksum Digit | Select this option to add a digit to the end of the generated OTP. This is used as a checksum to verify the OTP was generated correctly. This is in addition to the actual password length.Only set this if the user devices support it.Default: `Not enabled` | | HOTP Truncation Offset | This is an option used by the HOTP algorithm that not all devices support. Leave the default value unless you know user devices use an offset.Default: `-1` | | Store device data in shared state | Select this option to store the device data in the shared node state instead of in the user profile. When selected, the node adds the device data as a base64-encoded string to the `oathDeviceProfile` property in the shared node state. This string is decoded as an unescaped plain string representation of a JSON object. For example:In the shared node state:```none oathDeviceProfile="eyAidXVpZCI6ICJhNDhiMjUyMS0xYzliLTRiYTct...ja0RyaWZ0U2Vjb25kcyI6IDAgfQ" ```Decoded value:```json { "uuid": "a48b2521-1c9b-4ba7-a45c-8dd855c7397c", "recoveryCodes": [], "sharedSecret": "0CF9910A24CAF84E81CEBA71C2086DE4", "deviceName": "OATH Device", "lastLogin": 0, "counter": 0, "checksumDigit": false, "truncationOffset": -1, "clockDriftSeconds": 0 } ```Use the [OATH Device Storage node](oath-device-storage.html) to store the device data in the user profile instead. If you select this option, recovery codes aren't displayed at the end of the journey. They're stored as part of the oathDeviceProfile property in the shared node state.Default: `Not enabled` | (1) Specify a [locale that Java supports](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/Locale.html), such as `en-gb`. Otherwise, the node throws a configuration exception with an `Invalid locale provided` message. ## Outputs If the Store device data in shared state setting is enabled, this node records the device profile in the `oathDeviceProfile` shared state attribute. If the Generate Recovery Codes setting is enabled, this node records the recovery codes in the `oathEnableRecoveryCode` shared state attribute. ## Callbacks The node sends the following callbacks: * `TextOutputCallback` Contains the QR code message. * `HiddenValueCallback` Contains the registration URI used to generate the QR code. * `QRCodeCallback` Displays the QR code to the user. * `ConfirmationCallback` Lets the user continue after registering their device. Learn more in [Supported callbacks](https://docs.pingidentity.com/pingoneaic/am-authentication/callbacks-supported.html). ## Outcomes * `Success` Device registration succeeded. * `Failure` Any other case. ## Errors This node logs the following error messages: * `No username found.` The node failed to read the username from the shared state. * `No device profile found on shared state` The node failed to read the device profile from the shared state.