Access Management 7.3.1

Push authentication journeys

Configure authentication journeys (trees) for passwordless authentication and to receive push notifications.

When configured for passwordless authentication, the authentication flow requires the user to enter their user ID, but not their password. AM sends a push notification to their registered device to complete authentication with the ForgeRock Authenticator application.

Before implementing passwordless push authentication, consider the Limitations when using passwordless push authentication.

Configure the ForgeRock Authenticator (Push) service

In the AM admin UI, configure the ForgeRock Authenticator (Push) service for the realm where you create the tree.

This service specifies the user profile attribute that stores registered device metadata.

  1. In the AM admin UI for the realm, click Services > Add a Service.

  2. Select ForgeRock Authenticator (Push) Service in the service type drop-down list, and create the new service configuration.

  3. Accept the default configuration unless you must encrypt the device metadata in user profiles:

    Profile Storage Attribute

    pushDeviceProfiles (default)

    Device Profile Encryption Scheme

    If you choose an encryption scheme, also edit the settings to access the keys. For details about access to AM keys, read Secrets, certificates, and keys.

    Default: No encryption of device settings.

    ForgeRock Authenticator (Push) Device Skippable Attribute Name

    push2faEnabled (default)

    For additional details, refer to the reference documentation, ForgeRock Authenticator (Push) Service.

Configure the Push Notification service

In the AM admin UI, configure the Push Notification service for the realm.

AM 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. Log in to ForgeRock Backstage.

  2. Follow the instructions in How To Configure Service Credentials (Push Auth, Docker) in Backstage in the ForgeRock Knowledge Base.

    You can download the AWS credential data in JSON format and refer to that as you configure the service.

  3. In the AM admin UI for the realm, click Services > Add a Service.

  4. Select Push Notification Service in the service type drop-down list.

  5. Update the following fields with the data you generated on Backstage, then create the new service configuration:

    SNS Access Key ID

    The generated Key ID; the "accessKeyId" in the JSON

    SNS Access Key Secret

    The generated Secret; the "accessKeySecret" in the JSON

    SNS Endpoint for APNS

    The generated APNS; the "APNS" in the JSON

    SNS Endpoint for GCM

    The generated GCM; the "GCM" in the JSON

    For additional details, refer to the reference documentation, ForgeRock Authenticator (Push) Service.

Create a push authentication journey

The procedure assumes the following:

  • Users provide user IDs and passwords as the first step of multi-factor authentication (MFA).

  • AM sends the push notification to the device as an additional factor to complete authentication.

  • You have prepared the prerequisite services, described in Configure the ForgeRock Authenticator (Push) service and Configure the Push Notification service.

    1. In the AM admin UI under Realms > Realm Name > Authentication > Trees, create a tree for push notification.

    2. Add the following nodes to your tree:

    3. Connect the nodes as demonstrated in the following figure:

      Example push authentication tree
      Figure 1. Example push authentication tree
      Node connections
      List of node connections
      Source node Outcome path Target node

      Page Node containing:

      • Username Collector / Platform Username

      • Password Collector / Platform Password

      Data Store Decision

      Data Store Decision

      True

      Push Sender

      False

      Failure

      Push Sender

      Sent

      Push Wait

      Not Registered

      MFA Registration Options

      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

    4. Save your changes.

    5. Test your authentication tree as follows:

      1. Copy and paste the Preview URL into a browser in incognito mode. The URL looks something like: https://openam.example.com:8443/openam/XUI/?realm=alpha&authIndexType=service&authIndexValue=myPushAuthTree.

        A login screen prompting you to enter your user ID and password appears.

      2. Verify that you can use the ForgeRock Authenticator application to perform MFA.

        If the authentication tree is correctly configured, authentication is successful and AM displays the user profile page. For details, refer to Test push authentication.

Create a passwordless authentication journey

The procedure assumes the following:

  • Users provide only their user IDs as the first step of MFA.

  • Users have pre-registered a device for push authentication.

  • AM sends the push notification to the device as an additional factor to complete authentication, without the need for the user’s password.

  • You have prepared the prerequisite services, described in Configure the ForgeRock Authenticator (Push) service and Configure the Push Notification service.

    1. In the AM admin UI under Realms > Realm Name > Authentication > Trees, create a tree for passwordless authentication.

    2. Add the following nodes to your tree:

    3. Connect the nodes as demonstrated in the following figure:

      An authentication tree set up for passwordless push authentication.
      Figure 2. Passwordless push authentication
    4. Save your changes.

    5. Test your authentication tree as follows:

      1. Copy and paste the Preview URL into a browser in incognito mode. The URL looks something like: https://openam.example.com:8443/openam/XUI/?realm=alpha&authIndexType=service&authIndexValue=myPasswordlessAuthTree.

        A login screen appears, prompting you to enter your user ID.

      2. Verify that you can use the ForgeRock Authenticator application to perform MFA.

        If the authentication tree is correctly configured, authentication is successful and AM displays the user profile page without the user entering their password.

        For details, refer to Test push authentication.