Orchestration SDKs

Configuring Advanced Identity Cloud or PingAM for PingOne Protect

PingOne Advanced Identity Cloud PingAM Android iOS JavaScript

To perform PingOne Protect risk evaluations in your authentication journeys, you must set up your PingOne Advanced Identity Cloud or PingAM server to connect to your PingOne instances.

Complete the following tasks to configure your servers for PingOne Protect:

  1. Connect your server to PingOne Protect:

    You only have to do this task once.

    All PingOne services can reuse the same connection from your Advanced Identity Cloud tenant or PingAM server.

  2. Configure a journey to perform PingOne Protect risk evaluations.

Configuring Advanced Identity Cloud for PingOne Protect

Complete the following tasks to configure your Advanced Identity Cloud server, and your PingOne instance to perform risk evaluations.

Set up mapped PingOne environments

To integrate with PingOne, you need to set up a PingOne environment for each of your Advanced Identity Cloud tenant environments.

You also need to add the outbound static IP addresses of each of your Advanced Identity Cloud tenant environments to the server-sourced traffic exclusion list in the mapped PingOne environment. This prevents rate limits being applied to calls from PingOne Advanced Identity Cloud to PingOne services.

Learn more in Set up mapped PingOne environments.

Set up PingOne product connections

PingOne product connections are preconfigured OIDC integrations designed for quick setup. They streamline the connection process by automatically providing the necessary client credentials and PingOne environment ID within a signed JWT for easier consumption by PingOne Advanced Identity Cloud.

PingOne Advanced Identity Cloud can consume the JWT credential and automatically configure a worker service that’s ready to use in your authentication journeys.

To set up PingOne product connections, you will complete the following tasks:

  1. Create a product connection for your development tenant environment

  2. Create a PingOne integration in your development tenant environment

  3. Promote the integration to your other tenant environments

Learn more about this task in Set up PingOne product connections.

Now that you have configured Advanced Identity Cloud to connect to PingOne, you can create authentication journeys that leverage PingOne services, such as PingOne Protect. Learn more in Configure a journey to perform PingOne Protect risk evaluations.

Configuring PingAM for PingOne Protect

Complete the following tasks to configure your PingAM server, and your PingOne instance to perform risk evaluations.

  1. Create a worker application in PingOne

  2. Configure the PingOne Worker service in your server

Create a worker application in PingOne

To allow your server to access the PingOne administration API you must create a worker application in PingOne.

The worker application provides the client credentials your server uses to communicate with the PingOne admin APIs using the OpenID Connect protocol.

To create a worker application in PingOne:

  1. In the PingOne administration console, navigate to Applications  Applications, and then click Add ().

  2. In the Add Application panel:

    1. In Application name, enter a unique identifier for the worker application.

      For example, Orchestration SDK Worker.

    2. Optionally, enter a Description for the application and select an Icon.

      These do not affect the operation of the worker application but do help you identify it in the list.

    3. In Application Type, select Worker.

    4. Click Save.

  3. In the application properties panel for the worker application you created:

    1. On the Roles tab, click Grant Roles.

    2. On the Available responsibilities tab, select the Identity Data Admin row, and ensure the environment is correct.

    3. Click Save.

    4. On the Overview tab, ensure your worker application resembles the following image, and then enable it by using the toggle (1):

      Example worker application in PingOne
      Figure 1. Example worker application in PingOne

    5. Make a note of the Environment ID, Client ID, and Client Secret values (2).

      You need these values in the next step when you Configure the PingOne Worker service in your server.

Configure the PingOne Worker service in your server

After you create a worker application in PingOne, you must configure the PingOne Worker service in your server with the credentials.

Prerequisites

You need the following values from the PingOne Worker application you created in PingOne:

Client ID

Client ID of the worker application in PingOne.

Example: 6c7eb89a-66e9-ab12-cd34-eeaf795650b2

Client Secret

Client secret of the worker application in PingOne.

Use the Secret Mask () or Copy to Clipboard () buttons to obtain the value in the PingOne administration console.

Example: Ch15~o5Hm8N4_eS_m8~ARrV0KQAIQS6d.sJWe8TMXurEb~KWexY_p0gelR

Environment ID

Identifier of the environment that contains the worker application in PingOne.

Example: 3072206d-c6ce-ch15-m0nd-f87e972c7cc3

The PingOne Worker Service requires a configured OAuth2 provider service in your server.

Register the client secret in the server

You need to make the client secret of the worker application in PingOne available for use in the PingOne worker service.

Self-managed PingAM

For information on adding secret values for use in services in a self-managed PingAM instance, refer to Create key aliases in the PingAM documentation.

Configure the PingOne worker service

To configure the PingOne worker service:

  1. In the AM admin UI, click Services.

  2. If the PingOne Worker Service is in the list of services, select it.

  3. If you do not yet have a PingOne Worker Service:

    1. Click Add a Service.

    2. In Choose a service type, select PingOne Worker Service, and then click Create.

  4. On the Secondary Configurations tab, click Add a Secondary Configuration.

  5. On the New workers configuration page:

    1. Enter a Name for the configuration.

      For example, SDK PingOne Worker.

      You use this value when you configure an authentication journey that performs risk evaluations.

    2. In Client ID, enter the client ID of the PingOne Worker application you created earlier.

    3. In Client Secret Label Identifier, enter an identifier to create a specific secret label to represent the client secret of the worker application.

      For example, workerAppClientSecret.

      The secret label uses the template am.services.pingone.worker.identifier.clientsecret where identifier is the Client Secret Label Identifier value.

      This field can only contain characters a-z, A-Z, 0-9, and . and can’t start or end with a period.

    4. In Environment ID, enter the environment ID containing the PingOne Worker application you created earlier.

    5. Click Create

  6. On the Workers Configuration page, ensure that the PingOne API Server URL and PingOne Authorization Server URL are correct for the region of your PingOne servers:

    PingOne URLs by region
    Region Authorization URL API URL

    North America

    (Excluding Canada)

    https://auth.pingone.com

    https://api.pingone.com/v1

    Canada

    https://auth.pingone.ca

    https://api.pingone.ca/v1

    Europe

    https://auth.pingone.eu

    https://api.pingone.eu/v1

    Asia-Pacific

    https://auth.pingone.asia

    https://api.pingone.asia/v1

  7. Confirm your configuration resembles the image below, and then click Save changes.

    Example worker service configuration in PingAM
    Figure 2. Example worker application in PingOne

Map the Client Secret Label Identifier to a secret

To make the client secret available to the PingOne Worker Service, you must map the secret to the ID created.

Map secrets in self-managed PingAM

To learn about mapping secrets in self-managed PingAM, refer to Map and rotate secrets.

Now that you have configured PingAM to connect to PingOne, you can create authentication journeys that leverage PingOne services, such as PingOne Protect. Learn more in Configure a journey to perform PingOne Protect risk evaluations.

Configure a journey to perform PingOne Protect risk evaluations

To make risk evaluations in PingOne, you must configure an authentication journey in your server.

The following table covers the authentication nodes and callbacks for integrating your authentication journeys with PingOne Protect.

Node Callback Description

PingOne Protect Initialization node

PingOneProtectInitiateCallback

Instruct the embedded PingOne Signals SDK to start gathering contextual information.

PingOne Protect Evaluation node

PingOneProtectEvaluationCallback

Returns contextual information that the server can send to your PingOne Protect instance to perform a risk evaluation.

PingOne Protect Result node

Non-interactive

Inform the PingOne Protect instance about the status of the transaction.

These official PingOne Protect nodes are available in PingAM 7.5 and later, as well as PingOne Advanced Identity Cloud.

If you are using PingAM versions 7.2 to 7.4, you should instead use the equivalent PingOne Protect Marketplace nodes.

The PingOne Protect marketplace nodes use a MetadataCallback callback. The SDK recognizes the specific configuration the marketplace nodes place in this callback and can use it for use with PingOne Protect.

In your server, log in as an administrator and create a new authentication journey similar to the following example:

An example PingOne Protect journey
Figure 3. An example PingOne Protect journey

  • The PingOne Protect Initialize node 1 instructs the SDK to initialize the PingOne Protect Signals API with the configured properties.

    Initialize the PingOne Protect Signals API as early in the journey as possible, before any user interaction.

    This enables it to gather sufficient contextual data to make an informed risk evaluation.

    You can initialize the PingOne Protect Signals API whenever you want to start collecting data. This could be at application startup, or when a particular page or view is visited.

  • The user enters their credentials, which are verified against the identity store.

  • The PingOne Protect Evaluation node 2 performs a risk evaluation against a risk policy in PingOne.

    The example journey continues depending on the outcome:

    High

    The journey requests that the user respond to a push notification.

    Medium or Low

    The risk is not significant, so no further authentication factors are required.

    Exceeds Score Threshold

    The score returned is higher than the configured threshold and is considered too risky to complete successfully.

    Failure

    The risk evaluation could not be completed, so the authentication attempt continues to the Failure node.

    BOT_MITIGATION

    The risk evaluation returned a recommended action to check for the presence of a human, so the journey continues to a CAPTCHA node.

    ClientError

    The client returned an error when attempting to capture the data to perform a risk evaluation, so the authentication attempt continues to the Failure node.

  • An instance of the PingOne Protect Result node 3 returns the Success result to PingOne, which can be viewed in the audit console to help with analysis and risk policy tuning.

  • A second instance of the PingOne Protect Result node 4 returns the Failed result to PingOne, which can be viewed in the audit console to help with analysis and risk policy tuning.

Next steps

Select your platform to discover how to configure your client application to perform PingOne Protect risk evaluations when you are using Advanced Identity Cloud or PingAM auth journeys:

Android

Integrate Android apps with PingOne Protect auth journeys
iOS

Integrate iOS apps with PingOne Protect auth journeys
JavaScript

Integrate JavaScript apps with PingOne Protect auth journeys