PingOne Advanced Identity Cloud

Set up PingOne workers and configure them as Advanced Identity Cloud services

Integrate your Advanced Identity Cloud tenant environments with PingOne workers so that you can configure PingOne products (such as PingOne Protect and PingOne Verify) in your Advanced Identity Cloud authentication journeys.

PingOne workers are userless service applications that can perform administrative functions in PingOne. You connect to them from Advanced Identity Cloud using an access management service configured with the worker’s OpenID Connect (OIDC) credentials.

You only need to set up workers once for each of your Advanced Identity Cloud tenant environments and their mapped PingOne environments. You can then use the same worker service configuration in each of your Advanced Identity Cloud tenant environments.

Task 1: Create a worker application in each mapped PingOne environment

Create a worker application in each of your mapped PingOne environments. These provide access to the PingOne admin APIs using OpenID Connect (OIDC) credentials. In later tasks, you’ll configure each of your Advanced Identity Cloud tenant environments with these OIDC credentials.

In the PingOne admin console, perform the following steps for each of your mapped PingOne environments:

  1. In the sidebar, click the Ping Identity logo to open the Environments page.

  2. Click an environment in the list, then click Manage Environment.

  3. Go to Applications > Applications, then click the add icon ().

  4. In the Add Application panel:

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

      For example, PingOne Worker AIC.

    2. (Optional) Enter a Description for the application, select an Icon, or both. These don’t 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.

  5. 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, enable the worker application using the toggle switch in the top-right corner.

      Your worker application should now resemble the following image:

      Example worker application in PingOne

    5. Make a note of the following attributes in the Overview tab:

      Use the Secret Mask () or Copy to Clipboard () buttons to obtain the value of the client secret.
      Attribute name Description Example value

      Environment ID

      Identifier of the PingOne environment that contains the worker application.

      219617c6-02d8-4428-977d-5acc6fc0543e

      Client ID

      OIDC client ID of the worker application.

      faa04878-01ae-439c-8f22-162c2e0b03c0

      Client Secret

      OIDC client secret of the worker application.

      zcyE2heP43H5kEUw.VF8YvaXYZ9-ryEsGhTMw85h_NSiEdJvTd3EBDODEvEfCMEM

Task 2: Create ESVs for the worker application credentials in each tenant environment

Create ESVs (Environment Secrets and Variables) in each of your Advanced Identity Cloud tenant environments to hold the client credentials and environment IDs of the PingOne worker applications you created in task 1. Creating ESVs lets you configure Advanced Identity Cloud in a way that’s compatible with the promotion process.

In each of your Advanced Identity Cloud tenant environments, perform the following steps:

  1. Create the following ESVs using the attribute values from the tenant environment’s mapped PingOne environment.

    ESV name ESV type Expression type PingOne attribute value

    esv-pingone-environment-id

    Variable

    String

    Environment ID

    esv-pingone-worker-client-id

    Variable

    String

    Client ID

    esv-pingone-worker-client-secret

    Secret

    String

    Client Secret

    You can create variables and secrets using the Advanced Identity Cloud admin console or the API.

  2. Restart Advanced Identity Cloud services.

Task 3: Create a service in your development environment

Create a PingOne Worker Service in your Advanced Identity Cloud development environment and configure it with the OIDC credentials of the worker application in its mapped PingOne environment. The service is used in Advanced Identity Cloud authentication journey nodes to connect to the PingOne APIs.

Configure the service

In your development environment:

  1. In the Advanced Identity Cloud admin console, go to Native Consoles > Access Management.

  2. Click Services.

  3. Choose one of the following options:

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

    2. If not:

      1. Click Add a Service.

      2. In Choose a service type, select PingOne Worker Service, 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, PingOne Worker AIC.

      Make a note of this name. You’ll use this value when testing the integration and configuring PingOne authentication journey nodes.

    2. In the Client ID and Environment ID fields, enter the OIDC client ID and environment ID respectively of the worker application in the development environment’s mapped PingOne environment.

      Enter the literal values for these fields at this stage, not ESV placeholders. In later steps, you’ll replace the literal values with placeholders for their respective ESVs (esv-pingone-environment-id and esv-pingone-worker-client-id).

    3. In the Client Secret Label Identifier field, enter an identifier to create a specific secret label to represent the OIDC client secret of the worker application. For example, pingoneworkeraic. This field can only contain characters a-z, A-Z, 0-9, and . and can’t start or end with a period.

      In later steps, you’ll use this identifier to create a mapping to the esv-pingone-worker-client-secret ESV.

    4. 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:

    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

Map the Client Secret Label Identifier of the service to an ESV secret

To make the esv-pingone-worker-client-secret ESV available to the PingOne Worker Service, you must map it using the secret label identifier pingoneprotectworker.

In your development environment:

  1. In the Advanced Identity Cloud admin console, click Native Consoles > Access Management.

  2. 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, if you entered Client Secret Label Identifier of pingoneworkeraic the secret label will be am.services.pingone.worker.pingoneworkeraic.clientsecret.

    2. In aliases, enter the name of the ESV secret you created earlier (esv-pingone-worker-client-secret), then click Add.

    The result resembles the following:

    Example mapping of the Client Secret Label Identifier value.

  5. Click Create.

Learn more about mapping secrets and label identifiers for Advanced Identity Cloud in Secret labels.

Insert ESV placeholders into the service configuration

To make the esv-pingone-environment and esv-pingone-worker-client-id ESVs available to the PingOne Worker Service, you must replace the literal values in the worker service configuration with ESV placeholders.

In your development environment, follow the instructions in Insert ESV placeholders into the secondary configuration of a PingOne worker service.

Task 4: Test the integration

Use the testConnection action on the realm-config/services/pingOneWorkerService/workers/pingone-worker-service-name endpoint to test the connection from Advanced Identity Cloud to PingOne. When you send this request, Advanced Identity Cloud attempts to get an access token from PingOne using the worker service configuration.

To test the connection:

  1. Get an access token that has the fr:am:* scope.

  2. Test the connection from Advanced Identity Cloud to PingOne:

    $ curl \
--request POST 'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/realm-config/services/pingOneWorkerService/workers/<pingone-worker-service-name>?_action=testConnection' \(1) (2)
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Authorization: Bearer <access-token>'(3)
    1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
    2 Replace <pingone-worker-service-name> with the name of the PingOne worker service you created in task 3, ensuring that any spaces are URL encoded. For example, PingOne%20Worker%20AIC.
    3 Replace <access-token> with the access token created in step 1.

    If you get a 200 OK response, the integration is working correctly.

    If you get a 400 Bad Request, check the worker service configuration:

    • Ensure that the ESVs contain the correct values from the worker in the mapped PingOne environment.

    • Ensure that the ESVs are correctly mapped in the Advanced Identity Cloud service.

    Show 400 Bad Request response 
    {
    "code": 400,
    "reason": "Bad Request",
    "message": "Failed to retrieve PingOne Worker access token"
}

Task 5: Promote the integration to your other environments

Once you have successfully tested the integration in your development environment, you can promote the worker service configuration to your other environments (UAT[1], staging, production) using the standard promotion process.

  1. Determine the promotion order of your tenant environments. This will depend on whether you have a standard promotion group of environments or whether you also have additional UAT environments.

  2. In promotion order, for each of the tenant environments in your promotion group, perform the following steps:

    1. Ensure that the following ESVs are present and correctly set with values from the tenant environment’s mapped PingOne environment:

      • esv-pingone-environment-id

      • esv-pingone-worker-client-id

      • esv-pingone-worker-client-secret

    2. Run a promotion to move the configuration changes to the tenant environment from its respective lower tenant environment. Learn more in:

  3. (Optional) If you have sandbox[2] environments:

    1. Repeat task 3 for each of your sandbox environments to create a service.

    2. Repeat task 4 for each of your sandbox environments to test the integration.