Identity Cloud

Login with MFA using push notifications

While this use case was validated for accuracy, it can always be improved. To provide feedback, click thumb_up or thumb_down in the top right of this page (you must be logged into Backstage).

Description

Estimated time to complete: 30 minutes

In this use case, you authenticate a user with MFA by setting up the ForgeRock Authenticator application for push notification on a smartphone.

Goals

After completing this use case, you will know how to do the following:

  • Set configurations in the AM admin UI, such as configuring a service in Identity Cloud for push notifications.

  • Capture and validate a username and password.

  • Configure and register an end user’s device with their user profile in Identity Cloud.

  • Create a journey to enforce MFA at log in.

  • 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 ForgeRock concepts:

    • Realms

    • The AM admin UI

    • Journeys

    • Nodes

    • The Identity Cloud end-user UI

  • Access to your development environment as an administrator

  • An identity in Identity Cloud to test the journey (you may need to create this)

  • An Android or iOS smartphone with access to the internet

  • A ForgeRock Backstage account

Tasks

Task 1: Log in and configure the ForgeRock Authenticator Push service

  1. Log in to the Identity Cloud admin UI as an administrator.

  2. In the left menu pane, select Native Consoles > Access Management.

    The realm overview for the Alpha realm displays.

  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. For more information, refer to Configure the ForgeRock Authenticator (Push) service.

Task 2: Create Push service credentials in ForgeRock Backstage

Identity Cloud uses an external AWS service to send push notifications. Its configuration requires access keys and other metadata. As a ForgeRock customer, you have streamlined access to the required metadata:

  1. In a new tab, log in to ForgeRock Backstage.

  2. In the top right corner, click your profile icon > Profile.

  3. From the left mxenu pane, select Service Credentials.

  4. Under Push Notifications AWS Credentials, click Create.

    The push credentials page in Backstage

  5. In the Description field, enter Push credentials for MFA journey.

  6. Click Create.

  7. Click Download as JSON.

  8. Click Close.

  9. Close the ForgeRock Backstage tab.

Task 3: Configure the Push Notification service in the AM admin UI

  1. Click back to the tab that displays the AM admin UI.

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

  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 admin UI 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.

    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 admin UI tab.

  10. Click back to the Identity Cloud admin UI tab.

Task 4: Create the MFA using push notifications journey

Configure journey options

  1. In the Identity Cloud admin UI, click Journeys. All existing Identity Cloud journeys display.

  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. This is for the implementation guide.

    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 Identity Cloud environment.

    Tags

    Enter Implementation Guide

    Keywords for organizing the journeys list.

  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

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.

Click to display an example
Connecting two nodes together
Check in
First stage of the journey completed

At this point, the journey is configured to:

  • a Collect the username and password from the same page

  • b Validate the username and password

The following video demonstrates the steps up to this point in the procedure:

A video displaying the first stage of the journey

Send and verify push notifications

The journey goes down this path when the end user has a device registered with their 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

  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

At this point, the journey is configured to:

  • a Collect the username and password and present it on the same page.

  • b Validate the username and password.

  • c Send a push notification to the end user’s device.

  • d Validate the push notification.

Register device (smartphone) with 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 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 ForgeRock Authenticator application from the Apple App Store or the Google Play Store.

  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.

  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

At this point, the journey is configured to:

  • a Collect the username and password and present it on the same page.

  • b Validate the username and password.

  • c Send a push notification to the end user’s device.

  • d Validate the push notification sent.

  • e Prompt the user to download the application and register their device if Identity Cloud doesn’t find a device in the user’s profile.

  • 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 have now configured the journey successfully.

Check in
The journey completed

The completed journey has the following capabilities:

  • a Collect the username and password and present it on the same page.

  • b Validate the username and password.

  • c Send a push notification to the end user’s device.

  • d Prompt the end user to download the application and register their device if 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.

  • e Validate the push notification.

  • 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 have configured the ForgeRock Authenticator push service, the push notifications for Identity Cloud, and created your journey, you are ready to validate your journey.

Before validating, make sure you have 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 may 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 does not display the page to download the ForgeRock Authenticator application or to register a device. On the other hand, if the end user does not 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 does not have the ForgeRock Authenticator application on their smartphone and does not have a smartphone registered with their user profile in Identity Cloud.

  1. Get a URL you can use to test the journey:

    1. Log in to the Identity Cloud admin UI as an administrator.

    2. Select Journeys.

    3. Select the journey you created, Login with Push MFA. A preview screen of the journey displays.

    4. Click the copy icon next to Preview URL, a URL you can use to test a journey as an end user:

      Copying test URL of journey

  2. Log in to Identity Cloud:

    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.

      The login end-user UI displays.

    2. Enter the test user’s username and password.

    3. Click Next.

      A screen displays prompting you to download the ForgeRock Authenticator application.

  3. Download the ForgeRock Authenticator application:

    1. Click the Apple App Store or Google Play Store link, depending on which smartphone you have.

    2. Download the ForgeRock Authenticator application.

    3. After you have downloaded the ForgeRock Authenticator application, click Continue. A screen displays prompting you to scan a QR code.

  4. Register your user profile with your smartphone and copy recovery codes:

    1. Open the ForgeRock Authenticator application on your smartphone.

    2. Tap the blue + icon in the bottom right corner.

    3. Tap Scan QR Code.

    4. Scan the QR code that displays in your browser window with your smartphone’s. camera.

      A profile displays in the ForgeRock Authenticator application. Verify the test user’s username displays in the account created in the ForgeRock Authenticator application and that recovery codes display in the browser window.

    5. Copy the recovery codes.

      An end user can use recovery codes when they lose their device and need to log in.

    6. Click Done. A push notification is sent to your smartphone.

  5. Approve push notification and finish logging in:

    1. Tap Accept on your smartphone.

    2. Verify the acceptance by using your fingerprint or facial recognition.

      You should now be logged into the Identity Cloud end-user UI.

  6. Log out of Identity Cloud end-user UI:

    1. Click the test user’s name in the top right corner of the Identity Cloud end-user UI.

    2. Select Sign Out.

      You are redirected to a sign-in page. This page differs from the journey you created, Login with MFA Push. The page you are directed to when you sign out is the default journey in the realm. For more information on how to set the default journey, refer to "Default end-user journey" in Journeys.

Video of validation

The following video displays the expected validation as an end user registering their device and approving a push notification sent to their phone. The video doesn’t show the end user downloading the ForgeRock Authenticator application.

Explore further

Reference material

Reference Description

Realms

Realms are administrative units that group configurations and identities together.

Realms let you manage different sets of identities and applications within the same Identity Cloud tenant. Each realm is fully self-contained and operates independently of other realms within a tenant.

Admin interfaces in Identity Cloud

Get to know the admin interfaces; Identity Cloud admin UI, AM admin UI, and IDM admin UI.

Journeys

Conceptual information on journeys and their purpose in Identity Cloud.

Introduction to journeys with ForgeRock University

A guided video of journeys in Identity Cloud and how to use them.

Nodes for journeys

Learn about the configurable nodes Identity Cloud offers for use in journeys.

Marketplace nodes for journeys

Integrate third-party services into your applications or journeys with marketplace nodes.

Manage identities

Manage, group, and assign privileges to identities.

Themes

Customize the look and feel of login and end-user UI pages. This is used when you are using the ForgeRock hosted pages as your UI option.

Authenticate using push notification

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. To learn about each node in depth, refer to the following list:

The following nodes are listed in the order they appear in the journey.
Copyright © 2010-2024 ForgeRock, all rights reserved.