Combined MFA Registration node

Provides a way to register a device, such as a mobile phone for multi-factor authentication using both push notifications and OATH one-time passwords in a single step. This node can make your journeys less complex by combining the functionality of the Push Registration node and OATH Registration node.

The node displays a single QR code that users scan to register their device for both push and OATH authentication. Journeys can then use the Push Sender node to verify possession of a registered device. If push does not succeed, for example, the user’s device does not have internet access, the journey can fall back to using the OATH Token Verifier node to request a one-time passcode using OATH.

For more information about push notifications and OATH one-time passwords, refer to MFA: Authenticate using push notification and MFA: Use codes from ForgeRock app using OATH.

The node requires the username of the identity that is registering for MFA. For example, by using a Platform Username node.

You must also configure the Push Notification Service.

For information on provisioning the credentials required by the Push Notification Service, refer to How To Configure Service Credentials (Push Auth, Docker) in Backstage in the ForgeRock Knowledge Base.

Compatibility

Product	Compatible?
Advanced Identity Cloud	Yes
PingAM (self-managed)	Yes
Ping Identity Platform (self-managed)	Yes

Product

Compatible?

Advanced Identity Cloud

Yes

PingAM (self-managed)

Yes

Ping Identity Platform (self-managed)

Yes

Outcomes

Success
Failure
Time Out

If the user successfully registers their authenticator, evaluation continues along the Success outcome path.

If the node does not receive a response from the user’s device within the time specified in the node configuration, evaluation continues along the Time Out outcome path.

If AM encounters an issue when attempting to register using a device, evaluation continues along the Failure outcome path.

Properties

Property Usage

Issuer

Specify an identifier so that the user knows which service their account relates to. The value is displayed by the authenticator application.

For example, Example Inc. or the name of your application.

Account Name

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

Background Color

Specifies the background color, in hex notation, to display behind the issuer’s logo within the ForgeRock Authenticator application.

Logo Image URL

Specifies the location of an image to download and display as the issuer’s logo in the ForgeRock Authenticator application.

Generate Recovery Codes

Specify whether push-specific recovery codes should be generated. If enabled, recovery codes are generated and stored in transient state if registration was successful.

Use the Recovery Code Display node to display the codes to the user for safekeeping.

Generating recovery codes overwrites all existing push-specific recovery codes.

Only the most recent set of recovery codes can be used for authentication if a device has been lost or stolen.

QR code message

The message with instructions to scan the QR code to register the device.

Click Add. Enter the message locale in the Key field. For example, en-gb. Enter the message to display to the user in the Value field.

Registration Response Timeout

Specify the number of seconds to wait for a response from the authenticator.

If the specified time is reached, evaluation continues along the Time Out outcome path.

One Time Password Length (passwordLength)

The length of the generated OTP in digits.

This value must be at least 6 and 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.

Minimum Secret Key Length (minSharedSecretLength)

Number of hexadecimal characters allowed for the Secret Key.

Algorithm

Specify the algorithm your device uses to generate the OTP:

TOTP (default): TOTP generates a new OTP every few seconds as specified by the TOTP Time Step Interval value.
HOTP: HOTP uses a counter value that is incremented every time a new OTP is generated.

If this is set to HOTP, set the same value in the OATH Token Verifier node.

TOTP Time Step Interval (totpTimeInterval)

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.

The default value is 30.

TOTP Hash Algorithm (totpHashAlgorithm)

The HMAC hash algorithm used to generate the OTP codes. AM supports HMAC-SHA1, HMAC-SHA256, and HMAC-SHA512.

HOTP Checksum Digit (addChecksum)

Enable to add 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.

HOTP Truncation Offset (truncationOffset)

This is an option used by the HOTP algorithm that not all devices support. Leave the default value of -1 unless you know user devices use an offset.

JSON Authenticator Policies

Specifies the policies to apply to the device being registered and their parameters, in JSON format. Use the following format to enable policies:

{
    "policyName" : { policyParameters | empty }
}

Available policies

The ForgeRock Authenticator app supports enforcement of the following default policies:

biometricAvailable: Parameters: None

Require that the device has a biometric sensor available and enabled in the operating system.
deviceTampering: Parameters: score

Require that the device has not been tampered with, for example it has root access or is jailbroken.

This policy applies if the score returned by the device exceeds the provided score parameter, which is a number between 0 and 1.0.

Example:

{
  "biometricAvailable": { },
  "deviceTampering": {
    "score": 0.8
  }
}

Example

The following example shows one possible implementation of using the combined multi-factor registration node:

After verifying the user’s credentials using a Data Store Decision node, a Push Sender node determines if the user has a registered device or not.

If the user does have a registered device:: The Push Sender node sends their device a push notification, and loops back through a Push Wait node until the authentication succeeds or not.

The Push Wait node offers the user the option to cancel the wait for a push notification, in which case evaluation continues to the OATH Token Verifier node, so the user can enter a one-time passcode instead.
If the user does not yet have a registered device:: Evaluation continues to the Combined MFA Registration node, and a QR code is displayed to the user to register a device.

After successful registration of a device for both push and OATH authentication, evaluation returns to the Push Sender node path and continues now that the user does have a registered device.