Ping SDKs

ForgeRock Authenticator

ForgeRock Authenticator

Server support:

  • PingOne

  • PingOne Advanced Identity Cloud

  • PingAM

  • PingFederate

SDK support:

  • Ping SDK for Android

  • Ping SDK for iOS

  • Ping SDK for JavaScript

The ForgeRock Authenticator is an official multi-factor authentication (MFA) application for customers.

The ForgeRock Authenticator supports the following MFA methods:

You can also enable authentication app policies in the ForgeRock Authenticator that prevent operation on rooted devices, for example.

Download

Download the ForgeRock Authenticator from the following stores:

Develop

As a customer, you can use the Ping (ForgeRock) Authenticator module to integrate the functionality of the ForgeRock Authenticator into your own apps.

Implement your use cases with the ForgeRock Authenticator

Find out how to achieve some common use case scenarios using the ForgeRock Authenticator.

Mobile ForgeRock Authenticator

In this use case, you authenticate a user with MFA by setting up the ForgeRock Authenticator for .

To receive push notifications when authenticating, end users must register an Android or iOS device running the ForgeRock Authenticator.

Mobile Password Locked

In this use case you configure your server to require a single-use, one-time password generated by the ForgeRock Authenticator when users authenticate.

The ForgeRock Authenticator supports time-based and HMAC-based one-time passwords.

Compliance Report

You can distribute the ForgeRock Authenticator to your users so that they can participate in multi-factor authentication journeys.

To help ensure the security of the app—​and therefore your system—​you can apply Authenticator app policies.

Develop your own use case solutions

As a customer, you can use the Ping (ForgeRock) Authenticator module to integrate the functionality of the ForgeRock Authenticator into your own Android and iOS apps.

For more information, refer to Ping (ForgeRock) Authenticator module.

Implement MFA using push notifications

Applies to:

  • Ping SDK for Android

  • Ping SDK for iOS

  • Ping SDK for JavaScript

In this use case, you authenticate a user with MFA by setting up the ForgeRock Authenticator for .

To receive push notifications when authenticating, end users must register an Android or iOS device running the ForgeRock Authenticator.

The registered device can then be used as an additional factor when authenticating. Your server sends the device a push notification, which is handled by the ForgeRock Authenticator. In the app, you can allow or deny the request that generated the push notification and return the response to AM.

How push authentication works

An example of the interaction between the ForgeRock Authenticator (Push) journey, your server, and the ForgeRock Authenticator.
Figure 1. Overview of Push Authentication

The following steps occur as a user completes a push notification journey:

  1. The user provides credentials to enable AM to locate the user profile and determine if they have a registered mobile device.

  2. The journey prompts the user to register a mobile device if they have not done so already.

    The user registers their device by using the ForgeRock Authenticator. The application supports a variety of methods for responding to push notifications, such as tapping a button, or using biometrics.

    Registering a device stores device metadata in the user profile that is required for push notifications. AM uses the configured ForgeRock Authenticator (Push) service, which supports encrypting the metadata.

  3. Once the user has a registered device, AM creates a push message specific to the device.

    The message has a unique ID that AM stores while waiting for the response.

    AM writes a pending record with the same message ID to the CTS store for redundancy should an individual server go offline during the authentication process.

  4. AM sends the push message to the registered device.

    AM delivers the message through the configured push notification service.

    Depending on the registered device, AM uses either Apple Push Notification Services (APNS) or Google Cloud Messaging (GCM) to deliver the message.

    AM begins to poll the CTS for an accepted response from the registered device.

  5. The user responds to the notification through the ForgeRock Authenticator application on the device, for example, approving or rejecting the notification.

    The application responds to the push notification message with the user’s choice.

  6. AM verifies the message is from the correct registered device and has not been tampered with, and marks the pending record as accepted if valid.

    AM detects the accepted record and redirects the user to their profile page, completing the authentication.

Step 1. Enable the ForgeRock Authenticator Push service

In this step you configure your server to operate with the ForgeRock Authenticator. We will use the default settings.

  1. Log in to the PingOne Advanced 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, and then click Add a Service.

  4. In Choose a service type, select ForgeRock Authenticator (Push) Service, and then click Create.

  5. Click Save Changes to accept the default settings.

Step 2: Create Push service credentials in Backstage

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

  1. In a web browser, log in to the Service Credentials page on Backstage.

  2. Under Push Authentication AWS Credentials, click Create.

    backstage service credentials en
  3. In Description, enter Push credentials for MFA journey.

  4. In Region, select the location closest to the majority of your users.

  5. Click Create.

    The Create New AWS Credential screen displays the settings you must add to your server.

  6. Click Download as JSON.

    This downloads a file in JSON format containing all the values for you to store securely:

    Example of a downloaded JSON file with push service credential values
    {
      "id": "uzW8...rwJC",
      "provider": "AWS",
      "creationTimestamp": "2023-10-18T17:02:00.882Z",
      "createdBy": "admin.user",
      "updateTimestamp": null,
      "updatedBy": null,
      "description": "Push credentials for MFA journey",
      "supportKey": null,
      "validUntil": null,
      "writable": true,
      "region": "eu-west-1",
      "accessKeyId": "AKIA...6N74",
      "accessKeySecret": "uVjT...uu+k",
      "applicationArns": {
        "APNS": "arn:aws:sns:eu-west-1:1234:app/APNS/rgBO...n4RA",
        "GCM": "arn:aws:sns:eu-west-1:1234:app/GCM/rgBO...n4RA"
      }
    }
    json
    It is vital that you have a copy of these values, especially the accessKeySecret value, as it is not stored on Backstage.
  7. Click Close.

Step 3: Configure the Push Notification service in your server

In this step you configure your server with the settings it needs to be able to send push notifications to mobile devices.

You will need the AWS service credentials obtained in the previous step.

  1. Log in to the PingOne Advanced 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, and then click Add a Service.

  4. In Choose a service type, select Push Notification Service.

  5. Open the JSON file you obtained in the previous step:

    {
      "id": "uzW8...rwJC",
      "provider": "AWS",
      "creationTimestamp": "2023-10-18T17:02:00.882Z",
      "createdBy": "admin.user",
      "updateTimestamp": null,
      "updatedBy": null,
      "description": "Push credentials for MFA journey",
      "supportKey": null,
      "validUntil": null,
      "writable": true,
      "region": "eu-west-1",
      "accessKeyId": "AKIA...6N74", (1)
      "accessKeySecret": "uVjT...uu+k", (2)
      "applicationArns": {
        "APNS": "arn:aws:sns:eu-west-1:1234:app/APNS/rBO...n4A", (3)
        "GCM": "arn:aws:sns:eu-west-1:1234:app/GCM/rBO...n4A" (4)
      }
    }
    json
  6. Enter the fields from the JSON file into the fields that display:

    Field in PingOne Advanced Identity Cloud admin UI Field in JSON file Description

    SNS Access Key ID

    accessKeyId

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

    SNS Access Key Secret

    accessKeySecret

    The generated Secret; the "accessKeySecret" key in the JSON.

    SNS Endpoint for APNS

    APNS

    The generated APNS value; the "applicationArns/APNS" key in the JSON.

    The Apple Push Notification Service (APNS) endpoint that SNS uses to send push notifications to iOS devices.

    SNS Endpoint for GCM

    GCM

    The generated GCM value; the "applicationArns/GCM" key in the JSON.

    The Google Cloud Messaging (GCM) endpoint that SNS uses to send push notifications to Android devices.

    Do not enter the quotes that surround the JSON values.
  7. Click Create, and then click Save Changes.

Step 4: Create a push registration and authentication journey

In this step you create an authentication journey that registers a device running the ForgeRock Authenticator to the user’s profile if they have not done so already, then send a push notification to that device.

The journey then polls until it receives a response or timeout from the device. It verifies the returned data and completes the authentication journey if valid.

Choose whether you are creating the journey in PingOne Advanced Identity Cloud or a self-managed PingAM server, and follow the instructions to create the required authentication journey:

  1. In the PingOne Advanced Identity Cloud admin UI

    1. Select the realm that will contain the authentication journey.

    2. Select Journeys, and click New Journey.

    3. Enter a name for your tree in Name page; for example, MFAwithPush

    4. In Identity Object, select the identity type that will be authenticating, for example group Alpha realm - Users.

    5. Click Save.

      The authentication journey designer page is displayed with the default Start, Failure, and Success nodes.

  2. Add the following nodes to the designer area:

  3. Connect the nodes as shown:

    Connect the nodes to identify the user, send a push notification, and very the result.
    Figure 2. Connect the nodes to identify the user, send a push notification, and very the result.
  4. In the Push Sender node, select the type of push notification the journey sends to the ForgeRock Authenticator:

    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.

    For information on how these options appear in the ForgeRock Authenticator, refer to Authenticate using a push notification.

  5. Save your changes.

The tree you create is a simple example for the purposes of demonstrating a basic push authentication journey. In a production environment, you could include additional nodes, such as:

Get Authenticator App node

Provides links to download the ForgeRock Authenticator for Android and iOS.

MFA Registration Options node

Provides options for users to register a multi-factor authentication device, get the authenticator app, or skip the registration process.

Opt-out Multi-Factor Authentication node

Sets an attribute in the user’s profile which lets them skip multi-factor authentication.

Recovery Code Display node

Lets a user view recovery codes to use in case they lose or damage the authenticator device they register.

Recovery Code Collector Decision node

Lets a user enter their recovery codes to authenticate in case they have lost or damaged their registered authenticator device.

Retry Limit Decision node

Lets a journey loop a specified number of times, for example, in case the user’s device is experiencing connectivity issues, for example.

Step 5: Authenticate using a push notification

After creating the journey, you can register the ForgeRock Authenticator, and use it to respond to the push notificaiton message:

  1. If you have not already done so, create a demo user in your server:

  2. In an incognito browser window, browse to the journey you created in the previous step:

    Advanced Identity Cloud

    /XUI/?realm=alpha&authIndexType=service&authIndexValue=MFAwithPush

    Self-managed PingAM server

    /XUI/?realm=alpha&authIndexType=service&authIndexValue=MFAwithPush

    The journey asks for your credentials:

    Enter the credentials of your demo account.
  3. Sign in with the username and password of your demo user.

    If you have not yet registered the ForgeRock Authenticator, the journey displays a QR code:

    Register the Authenticator using the QR code.
  4. In the ForgeRock Authenticator, click the blue plus icon to register the account on the device:

    Click the plus icon to add an account in the Authenticator.
  5. In the Add Account menu that appears, select Scan QR Code:

    From the menu, select the Scan QR code option.
  6. Scan the QR code on screen using the ForgeRock Authenticator:

    Scan the QR code using the Authenticator.

    When the ForgeRock Authenticator registers the account it notifies your server, which then initiates the configured push notification.

  7. In the ForgeRock Authenticator, complete the authentication as requested:

    • If the journey is configured with the default Push Type setting, Tap to Accept, tap the Accept button:

      .Tap the Accept button.
      Figure 4. Tap the Accept button.
    • If the journey is configured with a Push Type setting of Display Challenge Code, tap the number in the ForgeRock Authenticator that matches the number displayed by the journey:

      .Tap the number in the app that matches the one displayed by the journey.
      Figure 5. Tap the number in the app that matches the one displayed by the journey.
    • If the journey is configured with a Push Type setting of Use Biometrics to Accept, tap the Accept button, and then use your devices biometric capabilities to complete authentication:

      Tap Accept, then use a biometric method to authenticate.
      Figure 6. Tap Accept, then use a biometric method to authenticate.

    After you successfully complete the required response, the browser displays the user’s profile page.

Next steps

You can add support for MFA using push notifications to your own Android and iOS applications, by using the Ping (ForgeRock) Authenticator module.

For more information, refer to Integrate MFA using push notifications.

Implement MFA using OATH one-time passwords

Applies to:

  • Ping SDK for Android

  • Ping SDK for iOS

  • Ping SDK for JavaScript

In this use case you configure your server to require a single-use, one-time password generated by the ForgeRock Authenticator when users authenticate.

Overview

The ForgeRock Authenticator supports one-time password (OTP) authentication as defined in the OATH standard protocols.

The following methods for generating one-time passwords are supported:

HMAC-based one-time passwords (HOTP)

As described in RFC 4226, HOTP authentication generates the one-time password (OTP) every time the user requests a new password on their device.

The device tracks the number of times the user requests a new one-time password with a counter. The user may be further in the counter on their device than the server.

Your server resynchronizes the counter when the user finally logs in. To accommodate this, you set the number of passwords a user can generate before their device cannot be resynchronized.

For example, if you set the HOTP Window Size to 50 and someone presses the button 30 times in the ForgeRock Authenticator to generate a new password, the counter in your server will review the passwords until it reaches the one-time password entered by the user.

If, however, someone presses the button 51 times, you will need to reset the counter to match the number on the device’s counter before the user can log in.

HOTP authentication does not check earlier passwords, so if the user attempts to reset the counter on their device, they will not be able to log in until you reset the counter on the server to match their device.

Time-based one-time passwords (TOTP)

As described in (RFC 6238), TOTP authentication constantly generates a new one-time password based on a time interval you specify.

The TOTP Time Step Interval setting configures how often a new password is generated by the ForgeRock Authenticator.

Use the TOTP Time Steps setting to provide a margin in case the time varies between your server and the device running the ForgeRock Authenticator. For example, set this to 1 to accept either the previous, the current, or the next password as valid.

Step 1. Create an OATH registration and authentication journey

In this step you create an authentication journey that registers a device running the ForgeRock Authenticator to the user’s profile if they have not done so already, then requests a one-time password from the device.

Choose whether you are creating the journey in PingOne Advanced Identity Cloud or a self-managed PingAM server, and follow the instructions to create the required authentication journey:

  1. In the PingOne Advanced Identity Cloud admin UI

    1. Select the realm that will contain the authentication journey.

    2. Select Journeys, and click New Journey.

    3. Enter a name for your tree in Name page; for example, MFAwithOATH

    4. In Identity Object, select the identity type that will be authenticating, for example group Alpha realm - Users.

    5. Click Save.

      The authentication journey designer page is displayed with the default Start, Failure, and Success nodes.

  2. Add the following nodes to the designer area:

  3. Connect the nodes as shown:

    Connect the nodes to identify the user, then verify their OATH token.
    Figure 7. Connect the nodes to identify the user, then verify their OATH token.
  4. Ensure that the OATH Token Verifier node and the OATH Registration node or Combined MFA Registration node are using the same value for OATH Algorithm.

    In this example, select TOTP.

  5. Save your changes.

The tree you create is a simple example for the purposes of demonstrating a basic OATH authentication journey. In a production environment, you could include additional nodes, such as:

Get Authenticator App node

Provides links to download the ForgeRock Authenticator for Android and iOS.

MFA Registration Options node

Provides options for users to register a multi-factor authentication device, get the authenticator app, or skip the registration process.

Opt-out Multi-Factor Authentication node

Sets an attribute in the user’s profile which lets them skip multi-factor authentication.

Recovery Code Display node

Lets a user view recovery codes to use in case they lose or damage the authenticator device they register.

Recovery Code Collector Decision node

Lets a user enter their recovery codes to authenticate in case they have lost or damaged their registered authenticator device.

Retry Limit Decision node

Lets a journey loop a specified number of times, for example, to allow a user to retry entering their OATH token.

Step 2. Authenticate using a one-time password

After creating the journey, you can register the ForgeRock Authenticator, and use it to generate and authenticate with a single-use, one-time password:

  1. If you have not already done so, create a demo user in your server:

  2. In an incognito browser window, browse to the journey you created in the previous step:

    Advanced Identity Cloud

    /XUI/?realm=alpha&authIndexType=service&authIndexValue=MFAwithOATH

    Self-managed PingAM server

    /XUI/?realm=alpha&authIndexType=service&authIndexValue=MFAwithOATH

    The journey asks for your credentials:

    Enter the credentials of your demo account.
  3. Sign in with the username and password of your demo user.

    If you have not yet registered the ForgeRock Authenticator, the journey displays a QR code:

    Register the Authenticator using the QR code.
  4. In the ForgeRock Authenticator, click the blue plus icon to register the account on the device:

    Click the plus icon to add an account in the Authenticator.
  5. In the Add Account menu that appears, select Scan QR Code:

    From the menu, select the Scan QR code option.
  6. Scan the QR code on screen using the ForgeRock Authenticator:

    Scan the QR code using the Authenticator.
  7. When the ForgeRock Authenticator registers the account, in your browser, click Next to continue the journey.

    The journey requests the one-time password:

    journey idcloud oath verify en
  8. Enter the verification code from the ForgeRock Authenticator.

    Enter the code the Authenticator displays for the account.

    If the animated timer indicates the one-time password is close to expiry, wait for the app to generate a new one.

    If you enter a valid one-time password, the browser displays the user’s profile page.

Next steps

You can add support for MFA using one-time passwords to your own Android and iOS applications, by using the Ping (ForgeRock) Authenticator module.

For more information, refer to Integrate MFA using OATH one-time passwords.

Secure the Authenticator app using policies

Applies to:

  • Ping SDK for Android

  • Ping SDK for iOS

  • Ping SDK for JavaScript

You can distribute the ForgeRock Authenticator app to your users so that they can participate in multi-factor authentication journeys. To help ensure the security of the app—​and therefore your system—​you can enable Authenticator app policies.

The Combined MFA Registration node can apply authenticator app policies during registration of client devices.

These policies can perform checks on the client device. For example, that the device has not been rooted or jailbroken, or verify the use of biometrics on the device.

If the conditions of the policy are not met, the account cannot be registered in the Authenticator app. If the conditions of the policies applied to the account are breached anytime after successful registration, the account is locked, and MFA is blocked:

Accounts that breach Authenticator app policies

Available policies

The Authenticator app supports the following policies by default:

Require biometrics

Policy name: biometricAvailable

Require the device uses biometric sensors to unlock the operating system.

Device tampering detection

Policy name: deviceTampering

Require the device has not been tampered with, for example, if it has root access or is jailbroken.

This policy applies if the tampering likelihood score returned by the device to the Authenticator app exceeds the provided score parameter, which is a number between 0 and 1.0. The higher the score, the more likely it is that the device has been tampered with.

Enable Authenticator app policies

Use the JSON Authenticator Policies property in the Combined MFA Registration node to enable policies.

Specify the policies and their parameters to apply to the device being registered in JSON format, as follows:

{
    "policyName" : { policyParameters | empty }
}
json

Example:

{
  "biometricAvailable": { },
  "deviceTampering": {
    "score": 0.8
  }
}
json

Next steps

You can add support for app policies in your own Android and iOS applications, by using the Ping (ForgeRock) Authenticator module.

For more information, refer to Integrate authenticator app policies.

Troubleshoot the ForgeRock Authenticator

Multi-factor authentication requires you to register a device, which is used as an additional factor when you log in to AM.

The following table summarizes different tasks related to devices used for multi-factor authentication:

Task Resources

Recover user accounts

Learn how to recover a user account when the user has lost their registered device, or when their device has become out of sync with AM.

Reset registered devices

In some scenarios, for example, when users are not able to access their recovery codes, you may need to reset their registered devices to allow them to register again.

Recover after replacing a lost device

If you register a device with AM and then lose it, you must authenticate to AM using a recovery code. After deleting the lost device, you can register a new device.

  1. Access the list of recovery codes you saved when registering the lost device.

    If you did not save the recovery codes when you registered the device, contact your administrator to remove the device from your user profile instead of following these steps.

  2. Begin to sign in as you normally would.

    When prompted to use a multi-factor option, click the Use Recovery Code link.

  3. Enter the recovery code when prompted.

    Because recovery codes are valid for a single use only, remove the code you used from your list.

    AM lets you sign in to access your profile page.

  4. Under Dashboard > Authentication Devices, click the context menu button for the lost device, and click Delete.

  5. Register your new device by signing out, then accessing the protected resource that requires MFA.

Recover after a device becomes out of sync

A device that generates one-time passwords can get out of sync with the OATH authentication service in some cases. If you repeatedly enter valid one-time passwords that appear to be valid passwords, but AM rejects the passwords as unauthorized, your device is likely out of sync.

To resynchronize your device, you must authenticate with a recovery code, and register the device again. Follow the steps in Recover after replacing a lost device.

If you did not save the recovery codes when you registered the device, contact your administrator to remove the device from your user profile instead.

Reset registered devices over REST

As described in Recover after replacing a lost device, a user who has lost a mobile phone registered with AM can register a replacement device by authenticating using a recovery code, deleting their existing device, and then registering a new device.

Additional support is required for users who lose mobile devices but did not save their recovery codes when they initially registered the device, and for users who have used up all their recovery codes.

AM provides a REST API to reset a device profile by deleting information about a user’s registered device. Both the user and administrator accounts can use the REST API to reset a device profile. Administrators can:

  • Provide authenticated users with a self-service page that calls the REST API to reset their devices.

  • Call the REST API themselves to reset a user’s device profiles.

  • Call the REST API themselves to reset a device that is out of sync, where the HOTP counter exceeds the HOTP threshold window and requires a reset.

Reset OATH devices

To reset a user’s OATH device profile, perform an HTTP POST to /users/{user}/devices/2fa/oath?_action=reset.

When making a REST API call, specify the realm in the path component of the endpoint.

Authenticate the request with the SSO cookie token belonging to an administrator.

The following example resets the OATH devices for a user in the alpha realm.

In PingOne Advanced Identity Cloud, use the _ID property of the user, not their username. The demo users' _id in this example is 014c54bd-6078-4639-8316-8ce0e7746fa4.

Reset OATH device
$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--header "<session-cookie-name>: AQIC5w…​2NzEz*" \
--data '{}' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/oath?_action=reset'
shell
Result
{
    "result":true
}
shell

The reset action deletes the OATH device profile, which by default has a limit of one profile per device, and sets the Select to Enable Skip option to its default value of Not Set.

Reset push devices

To reset push devices over REST, perform an HTTP POST to /users/{user}/devices/2fa/push?_action=reset.

When making a REST API call, specify the realm in the path component of the endpoint.

Authenticate the request with the SSO cookie token belonging an administrator.

The following example resets the push devices for a user in the alpha realm.

In PingOne Advanced Identity Cloud, use the _ID property of the user, not their username. The demo users' _id in this example is 014c54bd-6078-4639-8316-8ce0e7746fa4.

Reset push device
$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--header "<session-cookie-name>: AQIC5w…​2NzEz*" \
--data '{}' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/push?_action=reset'
shell
Result
{
    "result":true
}
shell

1. Use the combined MFA registration node if you intend to also add OATH one-time passwords as an MFA method.