Auth node reference

Push Registration node

The Push registration node lets a user register their device, such as a mobile phone for multi-factor authentication (MFA) using push notifications.

Learn more in the Push Authentication documentation for:

You can use the Combined MFA Registration node to register a device for use with both push notifications and one-time passcode (OATH) verification in a single step.

Availability

Product Available?

PingOne Advanced Identity Cloud

Yes

PingAM (self-managed)

Yes

Ping Identity Platform (self-managed)

Yes

Authenticators

The push-related nodes integrate with the ForgeRock Authenticator app for Android and iOS.

Third-party authenticator apps aren’t compatible with the push notification functionality.

Inputs

This node requires the realm and username properties in the incoming node state.

Implement a Username Collector node (standalone AM) or Platform Username node (Advanced Identity Cloud and Ping Identity Platform deployments) earlier in the journey.

Dependencies

You must configure the Push Notification service for the realm to use this node. Optionally, also configure the ForgeRock Authenticator (Push) service.

Find more information in the corresponding documentation for:

Find information on provisioning the credentials used by the service in How To Configure Service Credentials (Push Auth, Docker) in Backstage.

Configuration

Property Usage

Issuer

The name of the issuer or application so the user knows which service their account relates to.

This value is displayed in the authenticator app.

Issuer in authenticator app
ForegRock as the Issuer in the authenticator app

Account Name

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

If not specified, or if the specified profile attribute is empty, their username is used.

Background Color

The background color, in hex notation, to display behind the issuer’s logo within the authenticator app.

Logo Image URL

The location of an image to download and display as the issuer’s logo in the authenticator app.

Generate Recovery Codes

Select this option to generate push-specific recovery codes. When enabled, recovery codes are generated and stored in the transient state if registration is successful.

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

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 is lost or stolen.

QR code message

(Optional) Add a custom, localized message to display to the user 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.(2)

Default: Open your Authenticator app and tap the number shown to sign-in

Registration Response Timeout

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

As soon as the specified time is reached, evaluation continues along the Time Out outcome path.

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

(2) PingAM only: Learn more about customizing and translating default messages in Internationalize nodes.

Outputs

  • The node adds the pushDeviceProfiles attribute to the user’s profile with the device details on successful registration.

  • The node updates the shared state with the push device settings, the message ID and the push challenge.

  • If Generate Recovery Codes is enabled, the node records the recovery codes in the recoveryCodes shared state attribute. Use the Recovery Code Display node to display the codes to the user for safe keeping.

Outcomes

Success

The user successfully registered their authenticator app.

Failure

An issue occurred during device registration.

Time Out

A response wasn’t received from the user’s device within the time specified in the node configuration.

Errors

The node can log the following errors:

  • Unable to find push message ID

    The node failed to read the pushMessageId from the shared state and can’t proceed with registration. Make sure you have implemented a Push Sender node earlier in the journey.

  • Expected username to be set

    The node can’t identify the user from the shared state.

  • Unable to read service addresses for Push Notification Service

    The node can’t retrieve the push service URLs. Check that the Push Notification service is set up correctly in the realm.

  • Could not get messageId

    The node fails to retrieve the messageId and can’t proceed with registration.

  • The push message corresponds to <message type> message type which is not registered in the <realm name> realm

    The node can’t start the registration process. Check that the Push Notification service is set up correctly in the realm.

  • Failed to save device to user profile

    The node can’t save the device details to the user’s profile.

Examples

The following example shows one possible implementation of multi-factor push authentication, which uses this node:

Multi-factor push authentication
Node connections
List of node connections
Source node Outcome path Target node

Page Node containing nodes to collect credentials.

For standalone AM deployments, implement a Username Collector node and a Password Collector node.

For Advanced Identity Cloud and Ping Identity Platform deployments, implement a Platform Username node and a Platform Password node.

→

Data Store Decision

Data Store Decision

True

Device Profile Collector

False

Failure

Device Profile Collector

→

Push Sender

Push Sender

Sent

Push Wait

Not Registered

MFA Registration Options

Skipped

Success

Push Wait

Done

Push Result Verifier

Exit

Recovery Code Collector Decision

Push Result Verifier

Success

Success

Failure

Failure

Expired

Push Sender

Waiting

Push Wait

MFA Registration Options

Register

Push Registration

Get App

Get Authenticator App

Skip

Success

Opt-out

Opt-out Multi-Factor Authentication

Recovery Code Collector Decision

True

Success

False

Retry Limit Decision

Push Registration

Success

Recovery Code Display Node

Failure

Failure

Time Out

MFA Registration Options

Get Authenticator App

→

MFA Registration Options

Opt-out Multi-Factor Authentication

→

Success

Retry Limit Decision

Retry

Recovery Code Collector Decision

Reject

Failure

Recovery Code Display Node

→

Push Sender

After verifying the user’s credentials, evaluation continues to the Device Profile Collector node to collect the device’s location and then proceeds to the Push Sender node.

If the user has a registered device:

  1. The Push Sender node sends a push notification to their registered device.

  2. The Push Wait node pauses authentication for five seconds. During this time, the user can respond to the push notification on their device using the ForgeRock Authenticator app.

    If the user exits the Push Wait node, they’re directed to the Recovery Code Collector Decision node, where they can enter a recovery code to authenticate.

    Configure the Exit Message property in the Push Wait node with a message, such as Lost phone? Use a recovery code for situations like this.

    A Retry Limit Decision node allows three attempts to enter a recovery code before failing the authentication.

  3. The Push Result Verifier node verifies the user’s response:

    • If the user responds positively, they’re authenticated successfully and logged in.

    • If the user responds negatively, authentication fails.

    • If the push notification expires, the Push Sender node sends a new push notification.

      Use a Retry Limit Decision node to constrain the number of times a new code is sent.

    • If the user hasn’t yet responded, the flow loops back a step and the Push Wait node pauses authentication for another 5 seconds.

If the user doesn’t have a registered device:

  1. The MFA Registration Options node presents the user with the following options:

    Register Device

    The flow continues to the Push Registration node, which displays a QR code for the user to scan with their authenticator app.

    Get the App

    Displayed only if the node is configured to display Get Authenticator App. The flow continues to the Get Authenticator App node, which displays links to download the authenticator app.

    Skip this step

    Displayed only if the node is configured to allow users to skip registration. In this example, skipping is linked to the Success outcome. However, you could provide an alternative authentication flow using an Inner Tree Evaluator node for example.

    Opt-out

    Displayed only if the node is configured to allow users to skip registration. Evaluation continues to the Opt-out Multi-Factor Authentication node, which updates the user’s profile to skip MFA with push in the future. In this example, after updating the profile, the flow continues to the Success outcome.

  2. The user registers the device with the Push Registration node.

    After registration, the Recovery Code Display node displays the recovery codes to the user and the flow returns to the Push Sender node to continue push authentication.

To manage push devices, the user must log in using either the device or a recovery code.

Find more information in the MFA documentation for: