Authentication nodes

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.

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.

Example

The following journey includes both username-password and one-time passcode authentication:

OATH journey with device registration

Availability

Product Available?

PingOne Advanced Identity Cloud

Yes

PingAM (self-managed)

Yes

Ping Advanced Identity Software (self-managed)

Yes

Authenticators

The OATH-related nodes can integrate with the following authenticator apps:

Inputs

This node reads the username attribute and optionally the oathDeviceProfile attribute from the shared state.

Implement a Platform Username node earlier in the journey.

Dependencies

Confirm the user credentials before letting them register a device.

Implement a Platform Username node and a Platform Password node earlier in the journey.

Also implement a Data Store Decision node

Configuration

Property Usage Availability

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

All node versions

Account Name

Select the profile attribute to display as the username in the authenticator app.

v2.0 and later: If you require an attribute that isn’t listed, select Custom and enter the name of the required profile attribute in Custom Account Name Attribute.

If the selected profile attribute is empty or this option is not configured, the authenticator app uses the username.

Default: Username

All node versions

Custom Account Name Attribute RAPID only

This property only displays when Account Name is set to Custom. Enter the name of the profile attribute to display as the username in the authenticator app. For example, enter telephoneNumber to display the user’s phone number.

If the selected profile attribute is empty or this option is not configured, the authenticator app uses the username.

v2.0

Background Color

The background color in hex notation that displays behind the issuer’s logo within the authenticator app.

Default: 032b75

All node versions

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

All node versions

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 to display the codes to the user for safekeeping.

Default: Enabled

All node versions

QR code message

A custom, localized message with instructions to scan the QR code to register the device.

Add instructions

  1. Click .

  2. In the Key field, enter the locale. For example, en-gb.(1)

  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

All node versions

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

All node versions

Minimum Secret Key Length

The minimum number of hexadecimal characters allowed for the secret key.

Default: 40

All node versions

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.

TOTP

TOTP generates a new OTP every few seconds as specified by the TOTP Time Step Interval setting.

Default: TOTP

All node versions

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

All node versions

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

All node versions

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

All node versions

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

All node versions

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:

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

All node versions

Use JavaScript for QR Code RAPID only

Use JavaScript in the node response to display the QR code.

Default: Enabled

Disable this option if your environment blocks scripts in HTTP requests and responses.

When you disable this option, the frontend UI uses the URL in the HiddenValueCallback to render the QR code.

All node versions

(1) Specify a locale that Java supports, such as en-gb. Otherwise, the node throws a configuration exception with an Invalid locale provided message.

Outputs

  • The node sets the oathEnableRecoveryCode attribute in shared state to true if Generate Recovery Codes is enabled. Otherwise, it sets the attribute to false.

    The OATH Device Storage node reads this attribute when it stores the device data.

  • If Generate Recovery Codes is enabled, the node generates recovery codes on successful registration and stores them in the recoveryCodes transient state attribute. It stores the registered device name in the recoveryCodeDeviceName transient state attribute.

    The Recovery Code Display node displays these codes and device name when you place it after this node’s Success outcome.

  • If Store device data in shared state is enabled, the node stores the device profile in the oathDeviceProfile 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.

Outcomes

Success

Device registration succeeded.

Failure

Any other case.

Errors

The node can log the following:

Warnings

  • Custom account name attribute attribute name is not present on the user’s identity. Falling back to the username for the account name. RAPID only

    The node failed to read the custom account name attribute from the user’s profile and is using the username instead.

Errors

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

Changelog

Version Changes

2.0 RAPID only

Adds the ability to use any profile attribute as the username in the authenticator app. Select Custom in the Account Name configuration option to display Custom Account Name Attribute where you enter the required profile attribute.