Advanced Identity Cloud

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 to register a device for both push notifications and one-time passcode (OATH) verification in a single step.

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

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

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. PingOne Advanced Identity Cloud 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:

oathDeviceProfile="eyAidXVpZCI6ICJhNDhiMjUyMS0xYzliLTRiYTct...ja0RyaWZ0U2Vjb25kcyI6IDAgfQ"

Decoded value:

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