--- title: OATH Registration node description: Configure the OATH Registration node to let users register a device for OATH-based multi-factor authentication using a QR code scan. component: platform version: 7.5 page_id: platform:auth-node-ref:oath-registration canonical_url: https://docs.pingidentity.com/platform/7.5/auth-node-ref/oath-registration.html llms_txt: https://docs.pingidentity.com/platform/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["Nodes & Trees", "Journeys", "Authentication", "OAuth 2.0", "Registration", "Multi-factor Authentication (MFA)"] page_aliases: ["auth-node-oath-registration.adoc"] section_ids: availability: Availability authenticators: Authenticators inputs: Inputs dependencies: Dependencies properties: Properties outputs: Outputs outcomes: Outcomes errors: Errors example: Example --- # OATH Registration node The OATH Registration node lets the user register a device for OATH-based multi-factor authentication (MFA). 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 password (OATH) verification in a single step.Refer to the [OATH Token Verifier node example](oath-token-verifier.html#authn-mfa-oath-tree-example) that demonstrates how use to use other MFA nodes to create a complete OATH authentication journey. | ## 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: * The [ForgeRock Authenticator](https://docs.pingidentity.com/sdks/latest/authenticator/index.html) app for Android and iOS. * 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. ## Dependencies Confirm the user credentials before letting them register a device. For example, precede this node with the following nodes earlier in the authentication flow: * [Username Collector node](am-only/username-collector.html) (standalone AM) or [Platform Username node](platform-username.html) (Ping Identity Platform deployment) * [Password Collector node](am-only/password-collector.html) (standalone AM) or [Platform Password node](platform-password.html) (Ping Identity Platform deployment) * [Data Store Decision node](data-store-decision.html) ## Properties | Property | Usage | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Issuer | Specify an identifier to appear on the user's device, such as a company name, a website, or a realm.The authenticator application displays the value.Default: `ForgeRock` | | Account Name | Select the profile attribute to display as the username in the authenticator application.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 application.Default: `032b75` | | Logo Image URL | The location of an image to download and display as the issuer's logo within the authenticator application. The ForgeRock Authenticator 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 | If enabled, recovery codes are generated and stored 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: true | | QR code message | A custom, localized message with instructions to scan the QR code to register the device.1) Click Add. 2) Enter the message locale in the `Key` field; for example, `en-gb`. 3) Enter the message to display to the user in the `Value` field.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 | Number of hexadecimal characters allowed for the secret key.Default: `32` | | 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 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. Ping Identity Platform supports SHA1, SHA256, and SHA512.Default: `SHA1` | | HOTP Checksum Digit | This adds a digit to the end of the OTP generated to be 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: false | | 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 | If enabled, the device data isn't stored in the user profile on successful completion of the node. Instead, 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.Default: false | ## 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. ## 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. ## 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.