--- title: Configuring Advanced Identity Cloud and PingAM for PingOne Protect description: Explains the necessary server-side prerequisites for integrating PingOne Protect with Journeys, including configuring a PingOne worker application and service, and creating a Protect authentication journey. component: orchsdks page_id: orchsdks:journey:use-cases/protect/before-you-begin canonical_url: https://developer.pingidentity.com/orchsdks/journey/use-cases/protect/before-you-begin.html keywords: ["Journeys", "PingOne Protect", "Prerequisites", "Server Configuration", "Worker Application", "Worker Service"] section_ids: pingone-worker-app: Create a worker application in PingOne pingone-worker-service: Configure the PingOne Worker service in your server prerequisites: Prerequisites register_the_client_secret_in_the_server: Register the client secret in the server p1-worker-service: Configure the PingOne worker service map_the_client_secret_label_identifier_to_a_secret: Map the Client Secret Label Identifier to a secret map_secrets_in_advanced_identity_cloud: Map secrets in Advanced Identity Cloud map_secrets_in_self_managed_am: Map secrets in self-managed AM pingone-protect-journey: Configure a journey to perform PingOne Protect risk evaluations next_steps: Next steps --- # Configuring Advanced Identity Cloud and PingAM for PingOne Protect [icon: circle-check, set=far]PingOne Advanced Identity Cloud [icon: circle-check, set=far]PingAM [icon: android, set=fab]Android [icon: apple, set=fab]iOS [icon: js, set=fab]JavaScript In this step, you set up your PingOne Advanced Identity Cloud or PingAM server, and your PingOne instance to perform risk evaluations. 1. [Create a worker application in PingOne](#pingone-worker-app) 2. [Configure the PingOne Worker service in your server](#pingone-worker-service) 3. [Configure a journey to perform PingOne Protect risk evaluations](#pingone-protect-journey) ## Create a worker application in PingOne To allow your server to access the PingOne administration API you must create a [worker application](https://docs.pingidentity.com/pingone/applications/p1_applications_add_applications.html) 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** [icon: angle-right, set=fa] **Applications**, and then click Add ([icon: circle-plus, set=fas, size=lg]). 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](../../../_images/protect/pingone-worker-application-en.png)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](#pingone-worker-service). ## Configure the PingOne Worker service in your server After you [create a worker application](#pingone-worker-app) 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 ([icon: eye-slash, set=far]) or Copy to Clipboard ([icon: copy, set=far, flip=vertical]) 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.* If you are using a self-managed AM server, you must [configure the OAuth2 Provider service in a realm to expose the OAuth 2.0 endpoints and OAuth 2.0 administration REST endpoints.](https://docs.pingidentity.com/pingam/8/oauth2-guide/oauth2-configure-authz.html). * The OAuth2 provider service is preconfigured in Advanced Identity Cloud. | ### 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. * Advanced Identity Cloud If you are using Advanced Identity Cloud you will need to create an environment secret to hold the client secret value, as follows: 1. In the Advanced Identity Cloud admin UI, go to [icon: cog, set=fa]Tenant Settings > Global Settings > Environment Secrets & Variables. 2. Click the Secrets tab. 3. Click + Add Secret. 4. In the Add a Secret modal window, enter the following information: | | | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Name | Enter a secret name. For example, `ping-protect-client-secret`. Secret names cannot be modified after the secret has been created. | | Description | (optional) Enter a description of the purpose of the secret. | | Value | Enter the Client Secret value you obtained when creating the worker application in PingOne.For example, `Ch15~o5Hm8N4_eS_m8~ARrV0KQAIQS6d.sJWe8TMXurEb~KWexY_p0gelR`.The field obscures the secret value by default. You can optionally click the visibility toggle ([icon: eye-slash, set=fa]) to view the secret value as you enter it. | 5. Click Save to create the variable. 6. Click **View Update**, check the details of the new secret, and then click **Apply Update**. Advanced Identity Cloud displays a final confirmation page. ![aic save esv secret en](../../../_images/aic-save-esv-secret-en.png)Figure 2. Apply updated secrets in Advanced Identity Cloud 7. Click Apply Now. Advanced Identity Cloud propagates the new secret and its value to all servers. You **must** wait until the secrets have propagated throughout the environment before attempting to use the secret. The Environment Secrets & Variables page displays the following message while the update is in progress: ![aic esv propagate en](../../../_images/aic-esv-propagate-en.png)Figure 3. Propagating secrets in progress in Advanced Identity Cloud. * Self-managed AM For information on adding secret values for use in services in a self-managed AM instance, refer to [Create key aliases](https://docs.pingidentity.com/pingam/8/security-guide/configuring-keys.html#creating-new-keys) in the AM documentation. ### Configure the PingOne worker service To configure the PingOne worker service: 1. If you are using PingOne Advanced Identity Cloud, in the administration console navigate to Native Consoles > Access Management. 2. In the AM admin UI, click Services. 3. If the PingOne Worker Service is in the list of services, select it. 4. If you do not yet have a PingOne Worker Service: 1. Click [icon: plus, set=fa]Add a Service. 2. In Choose a service type, select `PingOne Worker Service`, and then click Create. 5. On the Secondary Configurations tab, click [icon: plus, set=fa]Add a Secondary Configuration. 6. 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 7. 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` | 8. Confirm your configuration resembles the image below, and then click Save changes. ![Example worker service configuration in AM](../../../_images/protect/pingone-worker-service-example-en.png)Figure 4. 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 Advanced Identity Cloud 1. In the Advanced Identity Cloud admin UI, click **Native Consoles > Access Management**. 2. In the AM admin UI (native console), go to **Realm > Secret Stores**. 3. Click the ESV secret store, then click Mappings. 4. Click + Add Mapping. 1. In Secret Label, select the label generated when you entered the Client Secret Label Identifier previously. For example, `am.services.pingone.worker.workerAppClientSecret.clientsecret`. 2. In aliases, enter the name of the ESV secret you created earlier, including the `esv-` prefix, and then click Add. For example, `esv-ping-protect-client-secret` The result resembles the following: ![Example mapping of the Client Secret Label Identifier value.](../../../_images/protect/pingone-worker-mapping-aic-en.png) 5. Click Create. To learn more about mapping secrets and label identifiers in Advanced Identity Cloud, refer to [Secret labels](https://docs.pingidentity.com/pingoneaic/latest/am-reference/secret-id-mappings.html). #### Map secrets in self-managed AM To learn about mapping secrets in self-managed AM, refer to [Map and rotate secrets](https://docs.pingidentity.com/pingam/8/security-guide/secret-mapping.html). You have now configured the PingOne Worker service in your server. You can now [Configure a journey to perform PingOne Protect risk evaluations](#pingone-protect-journey). ## 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](https://docs.pingidentity.com/auth-node-ref/latest/pingone/pingone-protect-initialize.html) | [PingOneProtectInitiateCallback](https://docs.pingidentity.com/pingoneaic/am-authentication/callbacks-interactive.html#PingOneProtectInitializeCallback) | Instruct the embedded PingOne Signals SDK to start gathering contextual information. | | [PingOne Protect Evaluation node](https://docs.pingidentity.com/auth-node-ref/latest/pingone/pingone-protect-evaluation.html) | [PingOneProtectEvaluationCallback](https://docs.pingidentity.com/pingoneaic/am-authentication/callbacks-interactive.html#PingOneProtectEvaluationCallback) | Returns contextual information that the server can send to your PingOne Protect instance to perform a risk evaluation. | | [PingOne Protect Result node](https://docs.pingidentity.com/auth-node-ref/latest/pingone/pingone-protect-result.html) | 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](https://backstage.forgerock.com/marketplace/entry/0N4Pho4BHzclhgZmJDZV).The PingOne Protect marketplace nodes use a [`MetadataCallback`](https://docs.pingidentity.com/pingoneaic/am-authentication/callbacks-read-only.html#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](../../../_images/protect/pingone-protect-example-journey.png)Figure 5. An example PingOne Protect journey * The [PingOne Protect Initialize node](https://docs.pingidentity.com/auth-node-ref/latest/pingone/pingone-protect-initialize.html) 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](https://docs.pingidentity.com/auth-node-ref/latest/pingone/pingone-protect-evaluation.html) 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](https://docs.pingidentity.com/auth-node-ref/latest/pingone/pingone-protect-result.html) 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](https://docs.pingidentity.com/auth-node-ref/latest/pingone/pingone-protect-result.html) 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: [icon: android, set=fab, size=3x] #### [Android](android/index.html) Integrate Android apps with PingOne Protect auth journeys [icon: apple, set=fab, size=3x] #### [iOS](ios/index.html) Integrate iOS apps with PingOne Protect auth journeys [icon: js, set=fab, size=3x] #### [JavaScript](javascript/index.html) Integrate JavaScript apps with PingOne Protect auth journeys