--- title: Sign on with MFA using push notifications description: "Estimated time to complete: 30 minutes" component: pingoneaic page_id: pingoneaic:use-cases:use-case-mfa-with-push canonical_url: https://docs.pingidentity.com/pingoneaic/use-cases/use-case-mfa-with-push.html keywords: ["Implementation Guide", "Use Case", "Multi-factor Authentication (MFA)"] page_aliases: ["implementation:use-case-mfa-with-push.adoc"] section_ids: mfa-push-description: Description mfa-push-goals: Goals mfa-push-prereqs: Prerequisites mfa-push-tasks: Tasks mfa-push-task-1: "Task 1: Sign on and configure the push service" mfa-push-task-2: "Task 2: Create Push service credentials in Backstage" mfa-push-task-3: "Task 3: Configure the Push Notification service in the AM native admin console" mfa-push-task-4: "Task 4: Create the MFA using push notifications journey" mfa-push-configure-journey-options: Configure journey options mfa-push-collect-credentials-one-page: Collect username, password, and validate login on one page mfa-push-send-verify-push-notifications: Send and verify push notifications mfa-push-register-device-with-idc-profile: Register device (smartphone) with Advanced Identity Cloud profile mfa-push-add-recovery-codes-send-push: Add recovery codes and send push notification to the new device mfa-push-task-5: "Task 5: Check journey path connections" mfa-push-validation: Validation mfa-push-validation-steps: Steps mfa-push-explore-further: Explore further mfa-push-reference-material: Reference material mfa-push-nodes-used: Nodes used --- # Sign on with MFA using push notifications ## Description Estimated time to complete: 30 minutes *(tooltip: This assumes you complete the prerequisites beforehand.)* In this use case, you authenticate a user with multi-factor authentication (MFA) by setting up the PingID app for push notifications on a smartphone. The push notifications are sent from Advanced Identity Cloud to the PingID app as an additional factor when signing on. ### Goals After completing this use case, you'll know how to do the following: * Configure services for push notifications in the AM native admin console. * Capture and validate a username and password. * Configure and register an end user's device with their user profile in Advanced Identity Cloud. * Create a journey to enforce MFA at sign on. * Provide recovery codes to end users if they lose their device. ## Prerequisites Before you start work on this use case, ensure you have these prerequisites: * A basic understanding of these Advanced Identity Cloud concepts: * Realms * The AM native admin console and hosted pages * Journeys * Nodes * Access to your development environment as a tenant administrator * An identity in Advanced Identity Cloud to test the journey (you might need to create this) * An Android or iOS smartphone with access to the internet * A Ping Identity Backstage account ## Tasks ### Task 1: Sign on and configure the push service 1. Sign on to the Advanced Identity Cloud admin console as a tenant administrator. 2. In the left menu pane, select Native Consoles > Access Management. The realm overview for the Alpha realm opens. 3. Select Services. 4. Click + Add a Service. 5. Create the push service configuration: 1. Select ForgeRock Authenticator (Push) Service in the service type drop-down list. 2. Click Create. 3. Click Save Changes to accept the default settings. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | The default settings don't encrypt the device metadata stored in user profiles. This use case accepts the default settings for simplicity. Learn more in [Configure the ForgeRock Authenticator (Push) service](../am-authentication/push-authentication-journeys.html#auth-mfa-push-fr-auth-service). | ### Task 2: Create Push service credentials in Backstage Advanced Identity Cloud uses an external AWS service to send push notifications. Its configuration requires access keys and other metadata. As a Ping Identity customer, you have streamlined access to the required metadata: 1. In a new tab, sign on to [Backstage](https://backstage.pingidentity.com). 2. In the top right corner, click your profile icon > Backstage Account. 3. On the left menu pane, select Service Credentials. 4. Under Push Notifications AWS Credentials, click Create. ![The push credentials page in Backstage](_images/mfa-with-push/use-case-mfa-with-push-creds-backstage.png) 5. In the Mobile Application field, select `PingID`. 6. In the Description field, enter `Push credentials for MFA journey.` 7. Click Create. 8. Click Download as JSON. 9. Click Close. 10. Close the Backstage tab. ### Task 3: Configure the Push Notification service in the AM native admin console 1. Click back to the tab that displays the AM native admin console. 2. Select Services. 3. Click + Add a Service. 4. To configure the Push Notification service, select Push Notification Service in the service type drop-down list. 5. Open the JSON file you [downloaded in step 8](#mfa-push-task-step-download-json-push-service-creds). 6. Enter the fields from the JSON file into the fields that display: | | | | - | ---------------------------------------------------- | | | Don't enter the quotes that surround the JSON value. | | Field in AM native admin console | Field in JSON file | Description | | -------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | SNS Access Key ID | accessKeyId | The generated Key ID; the `"accessKeyId"` in the JSON. | | SNS Access Key Secret | accessKeySecret | The generated Secret; the `"accessKeySecret"` in the JSON. To make this configuration compatible with the promotion process, create an ESV secret for the AWS Access Key Secret and replace the literal value with an ESV placeholder. Learn more in this KB article. | | SNS Endpoint for APNS | APNS | The generated APNS; the `"APNS"` in the JSON. Used to send push notifications to the Apple Push Notification Service (APNS). | | SNS Endpoint for GCM | GCM | The generated GCM; the `"GCM"` in the JSON. Used to send push notifications to Android devices using Google Cloud Messaging (GCM). | 7. Click Create. 8. Click Save Changes. 9. Close the AM native admin console tab. 10. Click back to the Advanced Identity Cloud admin console tab. ### Task 4: Create the MFA using push notifications journey #### Configure journey options 1. In the Advanced Identity Cloud admin console, go to Journeys > Journeys. 2. Click + New Journey. 3. Configure options for the new journey: | Field | Value | Description | | ----------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | Name | Enter `Login with Push MFA` | A name to display in the journeys list. | | Identity Object | Select `Alpha Realm - Users` | The type of object that this journey authenticates. | | Description | Enter `A login journey with MFA using push notifications` | Description of the journey. | | Override theme | Do not enable | Lets you provide a unique UI for this journey. | | Default journey for end users | Do not enable | Lets you designate this journey as the default journey for your Advanced Identity Cloud environment. | 4. Click Save. The journey editor displays. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | To save your progress, periodically click Save in the top right of the journey editor. Failure to do this results in losing your work if the page reloads or if you lose your network connection. | ![Journey editor screen](_images/mfa-with-push/use-case-mfa-with-push-journey-screen.png) #### Collect username, password, and validate login on one page 1. In the top left search bar, enter `Page Node`. A Page node combines multiple nodes that request input into a single page for display to the user. In this case, it allows the username and password boxes to display to the end user on the same page. 2. Drag the Page Node box from the left side of the journey editor to the right side (the canvas). 3. Connect the start (person) icon to the Page Node by selecting the icon and dragging it into the left side (input) of the Page Node. An arrow shows the flow of the journey from the person icon into the Page Node. When you connect nodes together, the arrows show the flow of the journey from node to node. 4. Search for the Platform Username node and drag it *into* the Page Node. The Platform Username node prompts the end user to enter their username and stores it in a configurable state attribute. 5. Search for the Platform Password node and drag it *into* the Page Node. The Platform Password node prompts the end user to enter their password and stores it in a configurable state attribute. 6. Search for the Data Store Decision node and drag it to the *right* of the Page Node. The Data Store Decision node verifies that the username and password values match those in the data store configured for the realm. 7. Connect the right side of the Page Node (the outcome) into the left side of the Data Store Decision node (input). 8. Connect the `False` outcome of the Data Store Decision node into the Failure node (red X circle). 9. In the top right of the journey editor, click Save. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | When connecting the outcome of a node to another node, make sure there is a hand icon present on the node you're connecting to.> **Collapse: Click to display an example** > > ![Connecting two nodes together](_images/mfa-with-push/use-case-mfa-with-push-connecting-nodes.gif) | Check in![First stage of the journey completed](_images/mfa-with-push/use-case-mfa-with-push-journey-username-password.png) At this point, the journey is configured to: 1. a Collect the username and password from the same page 2. b Validate the username and password #### Send and verify push notifications The journey goes down this path when the end user *has a device registered* with their Advanced Identity Cloud profile. 1. Search for the Push Sender node and drag it to the *right* of the Data Store Decision node on the canvas. 2. Connect the `True` outcome of the Data Store Decision node to the input of the Push Sender node. 3. Click the Push Sender node and configure its options: | Field | Value | Description | | ------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Message Timeout | Do not modify | Specifies the number of milliseconds the push notification message remains valid. | | User Message | Do not modify | Specifies an optional message to send to the end user on their device. | | Remove 'skip' option | Enable this property | Enable this option in the node to make the push authentication mandatory.When disabled, the user can skip the push authentication requested by the node and evaluation continues along the `Skipped` outcome path. | | Share Context Info | Enable this property | Enable this option to include context data, such as remoteIp, userAgent, and location, in the notification payload. | | Custom Payload Attributes | Do not modify | Include shared state objects in the message payload sent to the client. The size of the payload must not exceed 3 Kb or a `NodeProcessException` is thrown. | | Push Type | Select Display Challenge Code. | The type of push authentication the user must perform on their device to continue the journey. Select one of the following types:- Tap to accept: Requires the user to tap to accept. - Display Challenge Code: Requires the user to select one of three numbers displayed on their device. This selected number must match the code displayed in the browser for the request to be verified. - Use Biometrics to Accept: Requires the user's biometric authentication to process the notification. Research shows users might accept a push authentication without fully checking if it's legitimate. To reduce the chances of a user accepting a malicious push authentication attempt, select Display Challenge Code or Use Biometrics to Accept. | ![The push sender node configuration settings](_images/mfa-with-push/use-case-mfa-with-push-sender-node.png) 4. Search for the Push Wait Node and drag it to the right of the Push Sender node in the canvas. To let the end user respond to the push notification, the Push Wait node pauses authentication for the specified number of seconds while processing a push authentication request. 5. Connect the `Sent` outcome of the Push Sender node to the input of the Push Wait Node. 6. Search for the Push Result Verifier Node and drag it to the right of the Push Wait Node. The Push Result Verifier node works with the Push Sender node to validate the user's response to a previously sent push notification message. 7. Connect the `Done` outcome of the Push Wait Node to the input of the Push Result Verifier Node. 8. Connect the outcomes of the Push Result Verifier Node to various nodes: | Outcome path | Target node | | ------------ | ------------------------------- | | `Success` | Success node (green check mark) | | `Failure` | Failure node (red X) | | `Expired` | Push sender node | | `Waiting` | Push Wait Node | 9. Click Save. Check in![The second stage of configuring the journey, completed](_images/mfa-with-push/use-case-mfa-with-push-send-verify-push.png) At this point, the journey is configured to: 1. a Collect the username and password and present it on the same page. 2. b Validate the username and password. 3. c Send a push notification to the end user's device. 4. d Validate the push notification. #### Register device (smartphone) with Advanced Identity Cloud profile The journey goes down this path when the Push Sender node goes to the *Not Registered* outcome, signaling that the end user doesn't have a device registered with their Advanced Identity Cloud profile. 1. Search for the Get Authenticator App node and drag it *under* the Push Sender node. The Get Authenticator App node displays information to obtain the PingID app from the Apple App Store or the Google Play Store. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Make sure the URLs in the Get Authenticator App node configuration correctly link to the PingID app on the [Apple App Store](https://apps.apple.com/us/app/pingid/id891247102) and [Google Play](https://play.google.com/store/apps/details?id=prod.com.pingidentity.pingid). | 2. Connect the `Not Registered` outcome of the Push Sender node to the input of the Get Authenticator App node. 3. Search for the Push Registration node and drag it to the *right* of the Get Authenticator App node. | | | | - | ---------------------------------------------------------------------------------------------- | | | Make sure the value in the Issuer field in the Push Registration node configuration is `Ping`. | 4. Connect the outcome of the Get Authenticator App node to the input of the Push Registration node. 5. Connect the `Failure` outcome of the Push Registration node to the Failure node. 6. Connect the `Time Out` outcome of the Push Registration node to the Get Authenticator App node. 7. Click Save. Check in![The third stage of the journey, completed](_images/mfa-with-push/use-case-mfa-with-push-journey-register-device.png) At this point, the journey is configured to: 1. a Collect the username and password and present it on the same page. 2. b Validate the username and password. 3. c Send a push notification to the end user's device. 4. d Validate the push notification sent. 5. e Prompt the user to download the application and register their device if Advanced Identity Cloud doesn't find a device in the user's profile. 6. f Validate the push registration. #### Add recovery codes and send push notification to the new device 1. Search for the Recovery Code Display Node and drag it to the *right* of the Push Registration node. If the user's device is lost, the Recovery Code Display node retrieves generated recovery codes from the transient state and presents them to the user for safekeeping. The codes can be used to authenticate if a registered device is lost or stolen. 2. Connect the `Success` outcome of the Push Registration node as input to the Recovery Code Display Node. 3. Connect the outcome of the Recovery Code Display Node as input to the Push Sender node. 4. Search for the Recovery Code Collector Decision node and drag it to the *right* of the Push Wait Node. In the event the end user doesn't have access to or has lost their device, the Recovery Code Collector Decision node lets the end user authenticate with the recovery code provided in the Recovery Code Display node. 5. Connect the `Exit` outcome of the Push Wait Node as input to the Recovery Code Collector Decision node. 6. Connect the `True` outcome of the Recovery Code Collector Decision node to the Success node. 7. Search for the Retry Limit Decision node and drag it to the *right* of the Recovery Code Collector Decision node. The Retry Limit Decision node permits the specified number of passes through to the Retry outcome path before continuing evaluation along the Reject outcome path. In this case, it lets the end user reenter their recovery codes up to three times before the journey goes to the Failure node. 8. Connect the `False` outcome of the Recovery Code Collector Decision node as input to the Retry Limit Decision node. 9. Connect the `Retry` outcome of the Retry Limit Decision node as input to the Recovery Code Collector Decision node. 10. Connect the `Reject` outcome of the Retry Limit Decision node to the Failure node. 11. Click Save. You've now configured the journey successfully. Check in![The journey completed](_images/mfa-with-push/use-case-mfa-with-push-journey-completed.png) The completed journey has the following capabilities: 1. a Collect the username and password and present it on the same page. 2. b Validate the username and password. 3. c Send a push notification to the end user's device. 4. d Prompt the end user to download the application and register their device if Advanced Identity Cloud doesn't find a device on the user's profile. After registering their device, present the end user with recovery codes in the event they don't have access to or lose their device. Send the user a push notification. 5. e Validate the push notification. 6. f Prompt the end user to enter their recovery codes if a timeout occurs during push notification validation. Allow the end user up to three incorrect entries. ### Task 5: Check journey path connections The `MFA using push notifications` journey uses many nodes. Use the following table to compare the outcomes of each node and to validate that you wired the journey correctly. Many nodes can have more than one outcome. "→" denotes that a node only has one outcome path. | Source node | Outcome path | Target node | | ------------------------------------------------------------- | -------------- | -------------------------------- | | Start (person icon) | → | Page Node | | Page Node containing:- Platform Username - Platform Password | → | Data Store Decision | | Data Store Decision | True | Push Sender | | | False | Failure | | Push Sender | Sent | Push Wait Node | | | Not Registered | Get Authenticator App | | Push Wait Node | Done | Push Result Verifier Node | | | Exit | Recovery Code Collector Decision | | Push Result Verifier Node | Success | Success | | | Failure | Failure | | | Expired | Push Sender | | | Waiting | Push Wait Node | | Recovery Code Collector Decision | True | Success | | | False | Retry Limit Decision | | Retry Limit Decision | Retry | Recovery Code Collector Decision | | | Reject | Failure | | Get Authenticator App | → | Push Registration | | Push Registration | Success | Recovery Code Display Node | | | Failure | Failure | | | Timeout | Get Authenticator App | | Recovery Code Display Node | → | Push Sender | ## Validation Now that you've configured the ForgeRock Authenticator push service, the push notifications for Advanced Identity Cloud, and created your journey, you're ready to validate your journey. Before validating, make sure you've created a test user and have access to an Android or iOS smartphone. ### Steps In the journey you created, there are various paths the end user can go down, depending on their actions and the information in their user profile. For example, if the end user has a device (smartphone) registered with their profile, the journey doesn't display the page to download the PingID app or to register a device. On the other hand, if the end user doesn't approve the push notification in the specified time (defined in the Push Wait node in the journey), the journey prompts the user to enter a recovery code. To demonstrate the device registration process and push notification approval, this validation explores the path of an end user who doesn't have the PingID app on their smartphone and doesn't have a smartphone registered with their user profile in Advanced Identity Cloud. 1. Get a URL you can use to test the journey: 1. Sign on to the Advanced Identity Cloud admin console as an administrator. 2. Go to Journeys > Journeys. 3. Select the journey you created, Login with Push MFA. A journey preview page opens. 4. Click the copy icon next to the Preview URL, a URL you can use to test a journey as an end user: ![Copying test URL of journey](_images/mfa-with-push/use-case-mfa-with-push-validation-copy-url.png) 2. Sign on to the hosted account pages: 1. Paste the URL into an incognito window. Use incognito mode for testing to avoid caching issues, and so that any current sessions you have don't interfere with your test. 2. Enter the test user's username and password. 3. Click Next. A page opens prompting you to download the PingID app. 3. Download the PingID app: 1. Click the Apple App Store or Google Play Store link, depending on which smartphone you have. 2. Download the PingID app. 3. After you've downloaded the app, click Continue. A page opens prompting you to scan a QR code. 4. Register your user profile with your smartphone and copy recovery codes: 1. Open the PingID app on your smartphone. 2. Tap the blue Scan icon at the bottom of the screen. 3. Scan the QR code that displays in your browser window with your smartphone's camera. A new profile for the test user appears in the PingID app. 4. The browser displays a list of recovery codes. Copy these codes and save them in a secure location. You can use them to sign on if you lose access to your device. 5. Click Done. A push notification is sent to your smartphone. 5. Approve the push notification: 1. On your device, tap the number that matches the code displayed in the browser. 2. Tap Done. You should now be signed on to the hosted account pages. 6. Sign out of the hosted account pages: 1. Click the test user's name in the top right corner of the hosted account pages. 2. Select Sign Out. You're redirected to a sign-in page. This page differs from the journey you created, Login with MFA Push. The page you're directed to when you sign out is the *default* journey in the realm. Learn how to set the default journey in "Default end-user journey" in [Journeys](../journeys/journeys.html). ## Explore further ### Reference material | Reference | Description | | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Realms](../realms/realm-settings.html) | Realms are administrative units that group configurations and identities together.Realms let you manage different sets of identities and applications within the same Advanced Identity Cloud tenant. Each realm is fully self-contained and operates independently of other realms within a tenant. | | [Admin consoles in Advanced Identity Cloud](../getting-started/getting-started-explore-platform.html) | Get to know the admin interfaces; Advanced Identity Cloud admin console, AM native admin console, and IDM admin console. | | [Journeys](../journeys/journeys.html) | Conceptual information on journeys and their purpose in Advanced Identity Cloud. | | [Journey nodes](../journeys/auth-nodes.html) | Learn about the configurable nodes Advanced Identity Cloud offers for use in journeys. | | [Marketplace nodes for journeys](../journeys/marketplace.html) | Integrate third-party services into your applications or journeys with marketplace nodes. | | [Manage identities](../identities/manage-identities.html) | Manage, group, and assign privileges to identities. | | [Themes](../end-user/hosted-pages-customize.html) | Customize the look and feel of the hosted pages. This is used when you're using the Advanced Identity Cloud hosted pages as your UX option. | | [Authenticate using push notification](../am-authentication/authn-mfa-about-push.html) | A more in-depth reference on the configuration properties and the steps to create a journey with push notifications. | ### Nodes used The login with MFA using push notifications journey uses many nodes. Learn more about each node using the following list, which orders the nodes as they appear in the journey: * [Page node](https://docs.pingidentity.com/auth-node-ref/latest/page.html) * [Platform Username node](https://docs.pingidentity.com/auth-node-ref/latest/platform-username.html) * [Platform Password node](https://docs.pingidentity.com/auth-node-ref/latest/platform-password.html) * [Data Store Decision node](https://docs.pingidentity.com/auth-node-ref/latest/data-store-decision.html) * [Push Sender node](https://docs.pingidentity.com/auth-node-ref/latest/push-sender.html) * [Push Wait node](https://docs.pingidentity.com/auth-node-ref/latest/push-wait.html) * [Push Result Verifier node](https://docs.pingidentity.com/auth-node-ref/latest/push-result-verifier.html) * [Recovery Code Collector Decision node](https://docs.pingidentity.com/auth-node-ref/latest/recovery-code-collector-decision.html) * [Retry Limit Decision node](https://docs.pingidentity.com/auth-node-ref/latest/retry-limit-decision.html) * [Get Authenticator App node](https://docs.pingidentity.com/auth-node-ref/latest/get-authenticator-app.html) * [Push Registration node](https://docs.pingidentity.com/auth-node-ref/latest/push-registration.html) * [Recovery Code Display node](https://docs.pingidentity.com/auth-node-ref/latest/recovery-code-display.html)