Get Authenticator App node

The Get Authenticator App node displays information to get an authenticator app from the Apple App Store or the Google Play Store.

Availability

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

Product

Available?

PingOne Advanced Identity Cloud

Yes

PingAM (self-managed)

Yes

Ping Identity Platform (self-managed)

Yes

Inputs

None. This node doesn’t read shared state data.

Dependencies

This node has no dependencies.

Configuration

Property Usage

Property	Usage
Get App Authenticator Message	(Optional) Add a custom, localized message to display to the user. You can use the following variables to customize the message: `{{appleLink}}` `{{appleLabel}}` `{{googleLink}}` `{{googleLabel}}` You can also include HTML elements, for example: Apple: <a target='_blank' href='{{appleLink}}'>{{appleLabel}}</a> Add instructions Click . In the Key field, enter the locale. For example, `en-gb`.⁽¹⁾ In the Value field, enter the message. Click Done. Repeat to add more messages and save your changes when you’re done. Leave blank to use the default message.⁽²⁾ Default: `Get the app from the {{appleLink}} or on {{googleLink}}.`
Continue Label	(Optional) Add custom, localized text to display on the button the user can click to continue. Add instructions Click . In the Key field, enter the locale. For example, `en-gb`.⁽¹⁾ In the Value field, enter the message. Click Done. Repeat to add more messages and save your changes when you’re done. Leave blank to use the default message.⁽²⁾ Default: `Continue`
Apple App Store URL	The URL to download your authenticator app from the Apple App Store. The default value points to the ForgeRock Authenticator app for iOS. Default: `https://itunes.apple.com/app/forgerock-authenticator/id1038442926`
Google Play URL	The URL to download your authenticator app from the Google Play Store. The default value points to the ForgeRock Authenticator app for Android. Default: `https://play.google.com/store/apps/details?id=com.forgerock.authenticator`

Get App Authenticator Message

(Optional) Add a custom, localized message to display to the user. You can use the following variables to customize the message:

{{appleLink}}
{{appleLabel}}
{{googleLink}}
{{googleLabel}}

You can also include HTML elements, for example:

Apple: <a target='_blank' href='{{appleLink}}'>{{appleLabel}}</a>

Add instructions

Click .
In the Key field, enter the locale. For example, en-gb.⁽¹⁾
In the Value field, enter the message.
Click Done.
Repeat to add more messages and save your changes when you’re done.

Leave blank to use the default message.⁽²⁾

Default: Get the app from the {{appleLink}} or on {{googleLink}}.

Continue Label

(Optional) Add custom, localized text to display on the button the user can click to continue.

Add instructions

Click .
In the Key field, enter the locale. For example, en-gb.⁽¹⁾
In the Value field, enter the message.
Click Done.
Repeat to add more messages and save your changes when you’re done.

Leave blank to use the default message.⁽²⁾

Default: Continue

Apple App Store URL

The URL to download your authenticator app from the Apple App Store. The default value points to the ForgeRock Authenticator app for iOS.

Default: https://itunes.apple.com/app/forgerock-authenticator/id1038442926

Google Play URL

The URL to download your authenticator app from the Google Play Store. The default value points to the ForgeRock Authenticator app for Android.

Default: https://play.google.com/store/apps/details?id=com.forgerock.authenticator

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

⁽²⁾ PingAM only: Learn more about customizing and translating default messages in Internationalize nodes.

Outputs

This node doesn’t change the shared state.

Outcomes

Single outcome path.

Errors

This node doesn’t log any error or warning messages of its own.

Examples

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

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
Data Store Decision	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
Push Wait	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
Recovery Code Collector Decision	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
Retry Limit 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:

The Push Sender node sends a push notification to their registered device.
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.
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:

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