--- title: Push Registration node description: The Push registration node lets a user register their device, such as a mobile phone for multi-factor authentication (MFA) using push notifications. component: auth-node-ref version: latest page_id: auth-node-ref::push-registration canonical_url: https://docs.pingidentity.com/auth-node-ref/latest/push-registration.html keywords: ["Nodes & Trees", "Journeys", "Authentication", "Multi-factor Authentication (MFA)"] page_aliases: ["auth-node-push-registration.adoc"] superseded_by: https://docs.pingidentity.com/auth-node-ref/latest/push-registration.html section_ids: example: Example availability: Availability authenticators: Authenticators inputs: Inputs dependencies: Dependencies configuration: Configuration outputs: Outputs callbacks: Callbacks outcomes: Outcomes errors: Errors --- # 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 about Push Authentication in [MFA: Push authentication](https://docs.pingidentity.com/pingoneaic/am-authentication/authn-mfa-about-push.html). | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | You can use the [Combined MFA Registration node](combined-mfa-registration.html) to register a device for use with both push notifications and one-time passcode (OATH) verification in a single step. | ## Example The following example shows one possible implementation of multi-factor push authentication, which uses this node: ![Multi-factor push authentication](_images/push-nodes-example.png) > **Collapse: Node connections** > > **List of node connections** > > | Source node | Outcome path | Target node | > | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ----------------------------------- | > | Page Node containing nodes to collect credentials.Implement a [Platform Username node](platform-username.html) and a [Platform Password node](platform-password.html) earlier in the journey. | → | 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](device-profile-collector.html) to collect the device's location and then proceeds to the [Push Sender node](push-sender.html). **If the user *has* a registered device:** 1. The [Push Sender node](push-sender.html) sends a push notification to their registered device. 2. The [Push Wait node](push-wait.html) pauses authentication for five seconds. During this time, the user can respond to the push notification on their device using an authenticator app. If the user exits the [Push Wait node](push-wait.html), they're directed to the [Recovery Code Collector Decision node](recovery-code-collector-decision.html), where they can enter a recovery code to authenticate. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Configure the Exit Message property in the [Push Wait node](push-wait.html) with a message, such as `Lost phone? Use a recovery code` for situations like this. | A [Retry Limit Decision node](retry-limit-decision.html) allows three attempts to enter a recovery code before failing the authentication. 3. The [Push Result Verifier node](push-result-verifier.html) 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](push-sender.html) sends a new push notification. | | | | - | ----------------------------------------------------------------------------------------------------------------- | | | Use a [Retry Limit Decision node](retry-limit-decision.html) 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](push-wait.html) pauses authentication for another 5 seconds. **If the user *doesn't have* a registered device:** 1. The [MFA Registration Options node](mfa-registration-options.html) presents the user with the following options: * Register Device The flow continues to the [Push Registration node](push-registration.html), 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](get-authenticator-app.html), 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](inner-tree-evaluator.html) 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](opt-out-multi-factor.html), 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](push-registration.html). After registration, the [Recovery Code Display node](recovery-code-display.html) displays the recovery codes to the user and the flow returns to the [Push Sender node](push-sender.html) 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 [Manage devices for MFA](https://docs.pingidentity.com/pingoneaic/am-authentication/authn-mfa-devices.html). | ## 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 [PingID mobile app](https://docs.pingidentity.com/pingid-user-guide/pid_mobile_app/ug_pid_mobile_app_for_ios_and_android.html) and the [ForgeRock Authenticator app](https://docs.pingidentity.com/sdks/latest/authenticator/index.html) 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 [Platform Username node](platform-username.html) 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 [Push authentication journeys](https://docs.pingidentity.com/pingoneaic/am-authentication/push-authentication-journeys.html). Find information on provisioning the credentials used by the service in [How To Configure Service Credentials (Push Auth, Docker) in Backstage](https://backstage.pingidentity.com/knowledge/backstagehelp/article/a92326771). ## 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.> **Collapse: Issuer in authenticator app** > > ![ForegRock as the Issuer in the authenticator app](_images/authn-mfa-app-account-list.png) | | 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](recovery-code-display.html) 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:> **Collapse: Add instructions** > > 1. Click [icon: plus, set=fa]. > > 2. In the Key field, enter the locale. For example, `en-gb`.[(1)](#locale-footnote) > > 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: `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](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/Locale.html), such as `en-gb`. Otherwise, the node throws a configuration exception with an `Invalid locale provided` message. ## 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](recovery-code-display.html) to display the codes to the user for safe keeping. ## 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. * `PollingWaitCallback` Waits for the user to complete the registration process. The node waits for the number of seconds configured in the Registration Response Timeout. Learn more in [Supported callbacks](https://docs.pingidentity.com/pingoneaic/am-authentication/callbacks-supported.html). ## 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](push-sender.html) 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 which is not registered in the 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.