Combined MFA Registration node

The Combined MFA Registration node lets an authenticated user register a device, such as a mobile phone, for multi-factor authentication with a push notification and an OATH one-time password in a single step.

This node can make 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 use the Push Sender node to verify possession of the registered device. If push doesn’t succeed, for example, if the user’s device doesn’t have internet access, the journey can fall back to the OATH Token Verifier node to request a one-time password using OATH.

Learn more about push notifications and OATH one-time passwords in MFA: Push authentication and MFA: OATH authentication.

Compatibility

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

Product

Compatible?

PingOne Advanced Identity Cloud

Yes

PingAM (self-managed)

Yes

Ping Identity Platform (self-managed)

Yes

Inputs

The node reads the username of the identity that is registering for MFA from the shared state. Implement a Username Collector node (standalone AM) or Platform Username node (Ping Identity Platform deployment) before this node in the journey.

Dependencies

This node requires that you configure the Push Notification Service.

Learn more about provisioning the credentials required by the Push Notification Service in How To Configure Service Credentials (Push Auth, Docker) in Backstage in the ForgeRock Knowledge Base.

For detailed information about the available properties, refer to Push Notification Service.

Configuration

Property Usage

Issuer

An identifier to appear on the user’s device, such as a company name, a website, or a realm.

The value is displayed by the authenticator application.

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

Default: ForgeRock

Account Name

The profile attribute to display as the username in the authenticator application.

If not specified, or if the specified profile attribute is empty, the 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

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

A custom, localized 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.

Default: none

Registration Response Timeout

The period of time (in seconds) to wait for a response to the registration QR code. If no response is received during this time, evaluation continues along the Time Out outcome path.

Default: 60

One Time Password Length

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.

Default: 6

Minimum Secret Key Length

Minimum number of hexadecimal characters allowed for the Secret Key.

Default: 32

OATH Algorithm

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

Default: 30 seconds

TOTP Hash Algorithm

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

Default: SHA1

HOTP Checksum Digit

Add a digit to the end of the generated OTP 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

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

JSON Authenticator Policies

Policies to apply to the device being registered, in JSON format. Use the following format to apply policies:

{
    "[.var]#policyName#" : { "[.var]#policyParameters#" | [.label]#value# }
}

Supported policies

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

biometricAvailable: Parameters: None

The device must have a biometric sensor available and enabled in the operating system.
deviceTampering: Parameters: score

The device must not have been tampered with; for example have root access or be 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
  }
}

Outcomes

Success: Device registration succeeded.
Failure: AM encountered an issue when attempting to register the authentication device.
Time Out: The node didn’t receive a response from the device within the time specified in the configuration.

Outputs

For Push registration, this node updates the shared state with the push device settings, the message ID and the push challenge.
For OATH registration, this node records the device profile in the oathDeviceProfile shared state attribute and the recovery codes in the oathEnableRecoveryCode shared state attribute.

Errors

No username found: The node failed to read the username from the shared state.
Unable to find push message ID in sharedState: The node failed to read the push message ID from the shared state.

Example

The following example shows an implementation of combined multi-factor registration in an authentication journey:

The Page node with the Platform Username node and the Platform Password node prompts for the user credentials.
The Data Store Decision node confirms the username-password credentials.
The Push Sender node determines whether the user has a registered device.
- If the user has a registered device:
  - The Push Sender node sends a push notification to the device.
  - The Push Result Verifier node validate the user’s response to the push notification, looping through the Push Wait node until authentication succeeds.
  - The Push Wait node lets the user cancel the wait for a push notification. In this case evaluation continues to the OATH Token Verifier node, so the user can enter a one-time password instead.
- If the user doesn’t have a registered device:
  - The Push Sender node routes the user to the Combined MFA Registration node, which displays a QR code 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 and continues with the registered device.

PingAM 7.5.1