PingOne Advanced Identity Cloud

Threat detection with PingOne Protect

To protect against threats such as fraudulent sign-on attempts, you can incorporate threat detection into your PingOne Advanced Identity Cloud authentication journeys. The Ping Identity Marketplace includes a prebuilt authentication journey with threat detection that uses PingOne Protect to enable real-time monitoring of risk indicators, such as unusual login locations, device irregularities, or anomalous user behavior.

You can download this journey and import it into your Advanced Identity Cloud tenant. This guide details all the prerequisites and necessary configuration steps for using the journey.

This solution provides a sample journey as a template. Review and adapt it to meet your organization’s specific security policies and business requirements before deploying to a production environment.
Journey download
Journey name Version Download

Authentication Journey with Threat Detection

2.0

Download from Marketplace

Learn more about Threat detection using PingOne Protect.

About the threat detection journey

This solution uses a parent journey and inner journeys to evaluate the risk level of a user’s sign-on attempt.

Example use case

A company needs to identify and prevent fraudulent authentication when an end user attempts to sign on from an unusual geographical location. The goal is to reduce fraud while ensuring a frictionless experience for legitimate users.

With the Advanced Identity Cloud authentication with threat detection journey, the user’s geographical location is evaluated as part of a real-time threat detection process. If a user attempts to sign on from a location that exceeds a defined radius from the user’s expected location, it’s considered medium or high risk, depending on the extent of the deviation. The user is either prompted to step up with multi-factor authentication (MFA) or is denied access. If authentication is blocked or requires further verification, the user is notified by email or SMS to confirm that the attempt was legitimate.

Journey components

The threat detection journey includes one parent journey and seven inner journeys that work together to handle the authentication and threat detection flow.

Journey Description Configuration required?

Threat Detection Journey with PingOne Protect (parent journey)

Orchestrates the overall flow. It initializes variables, presents the sign-on page, calls the appropriate inner journeys, and records the final outcome for machine learning.

Yes

Threat Detection - Inner Journey

Uses the PingOne Protect nodes to initialize the SDK, capture user behavior signals, and evaluate risk.

Yes

MFA Device Registration - Inner Journey

Manages the flow for registering a new MFA device, if required.

Yes

MFA Authentication - Inner Journey

Handles the MFA challenge when a user needs to step up their authentication.

Yes

OATH Registration - Inner Journey

Sets the registration flow for OATH-based MFA.

No

Push MFA Method Registration - Inner Journey

Sets the registration flow for push-based MFA.

No

WebAuthn MFA Method Registration - Inner Journey

Sets the registration flow for WebAuthn-based MFA.

No

Combined OATH And PUSH MFA Methods Registration - Inner Journey

Sets the registration flow for OATH and push MFA.

No
Show the Threat Detection Journey with PingOne Protect (parent journey)
sample threat detection pingone protect journey

  • a A Scripted Decision node containing the initialize variables used in the authentication flow.

  • b The first call to the PingOne Protect Threat Detection - Inner Journey

  • c The second call to the PingOne Protect Threat Detection - Inner Journey for risk evaluation

  • d A call to the MFA Authentication - Inner Journey

  • e A call to the MFA Device Registration - Inner Journey

Task 1: Prepare your tenant environment

First, ensure you have the necessary prerequisites, then perform the required setup tasks in your tenant environment.

Before you begin

To implement the sample threat detection journey, you must have:

Setup tasks

To get the journey working, you’ll first need to perform some setup tasks in your Advanced Identity Cloud tenant environment.

Add custom attributes to the alpha_user managed object

Several additional user attributes are required by the threat detection user journey. These attributes store information about the user’s verified email, geographical location, operating system (OS), and MFA devices.

Add the following custom attributes to the alpha_user managed object. Learn more in Customize user identities using custom attributes.

Name Label Type Description

custom_emailVerified

Email verified

String

Confirms the user has verified their email address.

custom_protectActivityCity

PingOne Protect activity city

String

The city from which the user attempts to authenticate. This attribute is used in the Account Disabled and Suspicious Activity email templates.

custom_protectActivityState

PingOne Protect activity state

String

The state from which the user attempts to authenticate. This attribute is used in the Account Disabled and Suspicious Activity email templates.

custom_protectDeviceOS

PingOne Protect device OS

String

The OS of the device from which the user attempts to authenticate.

custom_mfaDevices

MFA devices

Array

Sets, fetches, and displays the user’s registered MFA devices.

custom_latestMFADevice

Latest used MFA device

String

The most recent MFA device registered by the user, used in the Device Registration FIDO email template.

(Optional) Set an ESV variable for PingOne Protect analysis

The Prerequisites & Init Variables node in the parent journey contains a script that uses the protectAnalysisRequired variable to determine if PingOne Protect analysis is enabled. By default, this variable is set to true within the script. To override this variable and control how PingOne Protect analysis is performed in different environments, you can set an Environment Secret & Variable (ESV) variable.

  1. In the Advanced Identity Cloud admin console, go to Tenant Settings > Global Settings > Environment Secrets & Variables.

  2. Click the Variables tab.

  3. Click + Add Variable.

  4. In the Add a Variable modal, enter the following information:

    Name

    p1-protect-analysis-required

    Type

    string

    Description (optional)

    PingOne Protect analysis required

    Value

    true

  5. Click Save to create the variable.

  6. Restart Advanced Identity Cloud services by applying updates in the Advanced Identity Cloud admin console.

Create the email templates

You’ll need to create the following email templates, which are used by Scripted Decision nodes to send emails at various points in the threat detection journey.

Email template Description Example email body

accountDisabled

Email sent when PingOne Protect detects critical risk associated with the account.
Show example 
<div style="display:block;width:400px;margin:0 auto;font-family:sans-serif;border:1px solid #c5c5c5;padding:30px 20px;text-align:center">
<img src="https://assets.pingone.com/ux/ui-library/5.0.2/images/logo-pingidentity.png" alt="Company Logo" style="height:65px;margin-bottom:10px" />
<div style="display:block">
<div style="display:inline-block;width:40px;height:40px;border-radius:50%;background-color:red;color:white;font-size:24px;line-height:40px;text-align:center">!</div>
<h2 style="margin-top:10px;margin-bottom:10px">Sign-in Attempt was blocked</h2>
<p>{{object.mail}}</p>
<hr style="width:100%;margin-top:20px;margin-bottom:25px;border:none;border-top:1px solid #c5c5c5" />
</div>
<div style="text-align:left">
<p id="alertText">Someone just attempted to sign onto your account nearby {{object.custom_protectActivityCity}}, {{object.custom_protectActivityState}}. We have disabled the account for your security. If this was you, please contact support.</p>
<p>Thanks,
      <br />The ${Brand Name} tea
    </p>
  </div>
</div>

deviceRegistration

Email sent when the user registers a new MFA device.
Show example 
<div style="display:block;text-align:center;font-family:'Arial',
  sans-serif;background-color:#f7f7f7;border:1px solid #e3e3e3;border-radius:10px;box-shadow:0 4px 8px rgba(0, 0, 0, 0.1);width:400px;margin:20px 20px;padding:30px 20px">
  <img src="https://assets.pingone.com/ux/ui-library/5.0.2/images/logo-pingidentity.png" alt="Company Logo" style="height:65px;margin-bottom:10px" />
  <h2 style="color:#333;font-size:24px;margin:20px 0">Sign On Device Added </h2>
  <p style="margin:20px 0 20px;font-size:16px;color:#555">The following device was successfully added to your
    account and can be used to authenticate. </p>
  <p style="margin:20px 0 20px;font-size:20px;color:#222">{{object.custom_latestMFADevice}}</p>
  <p style="margin:20px 0 20px;font-size:16px;color:#555">If you added this device, no further action is needed. </p>
  <p style="margin:20px 0 20px;font-size:16px;color:#555">If this device wasn't added by you, consider resetting
    your password to secure your account. </p>
</div>

suspiciousActivity

Email sent when PingOne Protect detects some risk associated with the account.
Show example 
<div style="display:block;width:400px;margin:0 auto;font-family:sans-serif;border:1px solid #c5c5c5;padding:30px 20px;text-align:center">
  <img src="https://assets.pingone.com/ux/ui-library/5.0.2/images/logo-pingidentity.png" alt="Company Logo" style="height:65px;margin-bottom:10px" />
  <div style="display:block">
    <div style="display:inline-block;width:40px;height:40px;border-radius:50%;background-color:red;color:white;font-size:24px;line-height:40px;text-align:center">!</div>
    <h2 style="margin-top:10px;margin-bottom:10px">Sign-in attempt detected</h2>
    <p>{{object.mail}}</p>
    <hr style="width:100%;margin-top:20px;margin-bottom:25px;border:none;border-top:1px solid #c5c5c5" />
  </div>
  <div style="text-align:left">
    <p id="alertText">Someone just attempted to sign onto your account nearby {{object.custom_protectActivityCity}}, {{object.custom_protectActivityState}}. If this was not you, please consider resetting your password or contact support. Otherwise, ignore.</p>
    <p>Thanks,
      <br />The ${Brand Name} team
    </p>
  </div>
</div>

welcome

Email sent when a new user account is created.
Show example 
<html>
  <head></head>
  <body style="background-color: #324054; color: #5e6d82; padding: 60px; text-align: center;">
    <p>Welcome. Your username is '{{object.userName}}'.</p>
  </body>
</html>

otp

Email containing the user’s one-time passcode (OTP).
Show example 
<html>
  <head></head>
  <body style="background-color: #324054; color: #455469; padding: 60px; text-align: center;">
    <div class="content" style="background-color: #fff; border-radius: 4px; margin: 0 auto; padding: 48px; width: 235px;">
      <p>
        <img src="https://www.pingidentity.com/content/dam/picr/nav/Ping-Logo-2.svg" alt>
        </p>
        <p>Hi {{object.givenName}}</p>
        <p>Here is your One Time Password. Please enter it into the login browser window:</p>
        <h1 id="objectotp">{{object.otp}}</h1>
        <p>PingOne Advanced Identity Cloud</p>
      </div>
    </body>
  </html>

Lean more about creating email templates in Email templates.

Create a logger library script for OTP

If you’re using OTP emails in your journey flow, you must create a library script. This script creates a logger, which is needed for OTP functionality to track and debug the process of sending OTP emails.

  1. In the Advanced Identity Cloud admin console, go to Scripts > Auth Scripts, then click + New Script.

  2. Select Other > Library and click Next.

  3. Enter a script name and description, and paste the following script into the JavaScript field:

    function XLogger(env) {
              this.logger = env.logger;
              this.scriptName = env.scriptName;
              this.logPrefix = "***" + env.scriptName + ": ";
              this.debug("logger initialised");
            }
            XLogger.prototype.debug = function (message) {
              this.logger.debug(this.logPrefix.concat(message));
            };
            XLogger.prototype.warn = function (message) {
              this.logger.warn(this.logPrefix.concat(message));
            };
            XLogger.prototype.error = function (message) {
              this.logger.error(this.logPrefix.concat(message));
            };
            module.exports.XLogger = XLogger;

  4. Click Save to save the script.

Task 2: Download and import the journey

Download the journey

  1. Go to Authentication Journey with Threat Detection on the Ping Identity marketplace.

  2. Click Download Integration to download a file called Authentication Journey with Threat Detection.json. This JSON file contains the parent journey and inner journeys, scripts, and email templates required for the authentication flow.

Import the journey

  1. In the Advanced Identity Cloud admin console, go to Journeys, and click Import.

  2. Click either Download Backup or Skip Backup. Learn more in Import journeys.

  3. On the Import Journeys page, browse to and select Authentication Journey with Threat Detection.json.

  4. Select Alpha realm users because the journey is configured for the alpha realm.

  5. In the Conflict Resolution section, choose how the system resolves import conflicts:

    • Overwrite all conflicts (default)

    • Manually pick conflict resolution

  6. Click Next.

  7. Click Start Import.

  8. On the Import Complete page, click Done.

  9. On the left panel of the Journeys page, click Threat Detection (8) to view the threat detection journeys and inner journeys.

Threat detaction journeys

Task 3: Configure the journey components

Configure the Threat Detection Journey with PingOne Protect (parent journey)

  1. On the Journeys page, click Threat Detection Journey with PingOne Protect and click Edit.

  2. In the journey editor, configure the journey as follows:

    1. Review and set the initialize variables.

    2. If you have configured social identity providers other than Google and Facebook, enable social identity providers.

  3. Click Save.

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.

Review and set the initialize variables

The Threat Detection Journey with PingOne Protect includes a Scripted Decision node containing the initialize variables used later in the authentication flow. This script lets you:

  • Set the allowed MFA types: FIDO2, OATH, PUSH, EMAIL, SMS, VOICE.

  • Enable or disable PingOne Protect analysis.

  • Enable or disable magic link.

To review and set the initial variables:

  1. Click the Prerequisites & Init Variables node.

  2. In the Script field, click the Pencil icon () to open the Threat Detection - Initialize Variables script.

  3. Review the script and make changes if needed.

  4. Click Save and Close.

You don’t need to update the values in the Script Outputs field of the Prerequisites & Init Variables node.

Enable social identity providers

  1. Click the Page node and then click the Select Identity Provider node.

  2. In the Filter Enabled Providers field, add or remove the social identity providers as needed. Only the social identity providers listed here will be presented to the end user when signing on.

    The social provider names must exactly match the names in your social authentication configuration, including the case.

  3. Click Save.

Configure the Threat Detection - Inner Journey

  1. On the Journeys page click Threat Detection - Inner Journey and click Edit.

  2. In the journey editor, configure the journey as follows:

    1. Click the PingOne Protect Initialize node.

    2. In the PingOne Worker Service ID field, select the ID of the PingOne worker service for connecting to PingOne. Learn more in PingOne Protect Initialize node.

    3. Click the Auth: PingOne Protect Evaluation node and enter the following:

      • PingOne Worker Service ID: Select the ID of the PingOne worker service for connecting to PingOne.

      • (Optional) Risk Policy Set ID: Enter the ID of the risk policy in PingOne. Learn more in PingOne Protect Evaluation node

    4. Click the Reg: PingOne Protect Evaluation node and enter the following:

      • PingOne Worker Service ID: Enter the ID of the PingOne worker service for connecting to PingOne.

      • (Optional) Risk Policy Set ID: Enter the ID of the risk policy in PingOne. Learn more in PingOne Protect Result node.

  3. Click Save.

Configure the MFA Device Registration - Inner Journey

This configuration is required if SMS or VOICE are opted in the allowedMFATypes array in the Threat Detection - Initialize Variables script in the Prerequisites & Init Variables node in the parent journey.

  1. On the Journeys page, click MFA Device Registration - Inner Journey and click Edit.

  2. In the journey editor, update the required fields in the following nodes:

  3. Click Save.

Configure the MFA Authentication - Inner Journey

This configuration is required if EMAIL, SMS, or VOICE are opted in the allowedMFATypes array in the Threat Detection - Initialize Variables script in the Prerequisites & Init Variables node in the parent journey.

  1. On the Journeys page, click MFA Authentication - Inner Journey and click Edit.

  2. In the journey editor, update the required fields in the following nodes:

  3. Click Save.

Task 4: Validate the journey

There are various paths the end user might go down, depending on the PingOne Protect risk evaluation and the MFA methods configured in the journey. For example, a user identified as low risk can sign on without MFA. However, for medium or high-risk sign-on attempts, the journey prompts the user to choose an MFA method, which could involve registering a new device. If a user signing on for the first time is identified as high risk, the registration attempt is blocked.

Before validating the journey, make sure you have a test user in the alpha realm. To authenticate using an OTP, the user must have a registered authenticator app.

Test a medium-risk sign-on

These steps demonstrate a sign-on attempt by an end user identified as medium risk.

  1. In the Advanced Identity Cloud admin console, go to Journeys and click Threat Detection Journey with PingOne Protect`.

  2. In the Preview URL field, click copy and paste the URL into an incognito window.

    The Advanced Identity Cloud end-user UI displays the Sign In screen.

    Threat detaction journey sign in screen

  3. Enter the test user’s username and password and click Next.

    A page displays prompting the user to select their preferred authentication method for MFA.

  4. Select OATH and click Next.

    Select MFA method

  5. Enter the OTP from the test user’s app, and click Submit

    Select MFA method

    You are signed on to the Advanced Identity Cloud end-user UI as the test user.

Best practices

This sample journey provides a strong foundation for threat detection. When preparing to use it in a production environment, consider the following best practices:

  • Treat as a template: Remember that this is a sample journey. Always adapt and harden it to meet your specific security policies and business requirements before deploying to production.

  • Use Environment Secrets & Variables (ESVs): Avoid hardcoding sensitive information like API keys and IDs directly in your journey scripts. Use ESVs to manage these values securely.

  • Test extensively: Validate all possible user paths, including low, medium, and high-risk scenarios, as different MFA registration and authentication flows. Ensure the user experience is smooth and the security responses are correct for each case.

  • Review PingOne Protect policies: Fine-tune your risk policies in PingOne Protect to align with your organization’s risk tolerance.