--- title: PingOne Advanced Identity Cloud description: This guide provides examples of how to use PingGateway with PingOne Advanced Identity Cloud for Single Sign-On and API Security. It is for PingOne Advanced Identity Cloud evaluators, administrators, and architects. component: pinggateway version: 2024.11 page_id: pinggateway:identity-cloud-guide:preface canonical_url: https://docs.pingidentity.com/pinggateway/2026/aic/preface.html llms_txt: https://docs.pingidentity.com/pinggateway/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2024-05-23T15:29:10Z keywords: ["Single sign-on (SSO)", "Security", "URI", "Authenticate", "Agents", "Journeys", "Nodes & Trees"] page_aliases: ["index.adoc"] section_ids: preface-examples: Example installation for this guide authenticate-agent-idc: Authenticate a PingGateway agent to PingOne Advanced Identity Cloud register-agent-idc: Register a PingGateway agent in PingOne Advanced Identity Cloud idc-use-the-secret-store-for-the-password: Use the secret store for the password optional_settings: Optional settings setup-user-idc: Set up a demo user in PingOne Advanced Identity Cloud idc-recommendations: Recommendations --- # PingOne Advanced Identity Cloud This guide provides examples of how to use PingGateway with PingOne Advanced Identity Cloud for Single Sign-On and API Security. It is for PingOne Advanced Identity Cloud evaluators, administrators, and architects. ## Example installation for this guide Unless otherwise stated, the examples in this guide assume the following installation: * PingGateway installed on `http://ig.example.com:8080`, as described in the [Install](../installation-guide/preface.html) . * Sample application installed on `http://app.example.com:8081`, as described in [Use the sample application](../getting-started/start-sampleapp.html). * An PingOne Advanced Identity Cloud tenant with the default configuration, as described in the [PingOne Advanced Identity Cloud documentation](https://docs.pingidentity.com/pingoneaic/latest/home.html). When using PingOne Advanced Identity Cloud, you need to know the value of the following properties: * The root URL of your PingOne Advanced Identity Cloud tenant. For example, `https://myTenant.forgeblocks.com`. The URL of the PingAM component of PingOne Advanced Identity Cloud is the root URL of your PingOne Advanced Identity Cloud tenant followed by `/am`. For example, `https://myTenant.forgeblocks.com/am`. * The realm where you work. The examples in this document use `alpha`. Prefix each realm in the hierarchy with the `realms` keyword. For example, `/realms/root/realms/alpha`. If you use a different configuration, substitute in the procedures accordingly. ## Authenticate a PingGateway agent to PingOne Advanced Identity Cloud | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | PingGateway agents are automatically authenticated to PingOne Advanced Identity Cloud by a non-configurable authentication module. Authentication chains and modules are deprecated in PingOne Advanced Identity Cloud and replaced by journeys.You can now authenticate PingGateway agents to PingOne Advanced Identity Cloud with a journey. The procedure is currently optional, but will be required when authentication chains and modules are removed in a future release of PingOne Advanced Identity Cloud.Learn more in the PingOne Advanced Identity Cloud documentation on [Journeys](https://docs.pingidentity.com/pingoneaic/latest/realms/journeys.html). | This section describes how to create a journey to authenticate an PingGateway agent to PingOne Advanced Identity Cloud. The journey has the following requirements: * It must be called `Agent` * Its nodes must pass the agent credentials to the Agent Data Store Decision node. When you define a journey in PingOne Advanced Identity Cloud, that same journey is used for all instances of PingGateway, Java agent, and Web agent. Consider this point if you change the journey configuration. 1. Log in to the Advanced Identity Cloud admin UI as an administrator. 2. Click Journeys > New Journey. 3. Add a journey with the following information and click Create journey: * Name: `Agent` * Identity Object: The user or device to authenticate. * (Optional) Description: Authenticate a PingGateway agent to PingOne Advanced Identity Cloud The journey designer is displayed, with the `Start` entry point connected to the `Failure` exit point, and a `Success` node. 4. Using the [icon: search, set=fa]Filter nodes bar, find and then drag the following nodes from the Components panel into the designer area: * [Zero Page Login Collector](https://docs.pingidentity.com/auth-node-ref/latest/auth-node-zero-page-login-collector.html) node to check whether the agent credentials are provided in the incoming authentication request, and use their values in the following nodes. This node is required for compatibility with Java agent and Web agent. * [Page](https://docs.pingidentity.com/auth-node-ref/latest/page.html) node to collect the agent credentials if they aren't provided in the incoming authentication request, and use their values in the following nodes. * [Agent Data Store Decision](https://docs.pingidentity.com/auth-node-ref/latest/auth-node-agent-data-store-decision.html) node to verify the agent credentials match the registered PingGateway agent profile. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Many nodes can be configured in the panel on the right side of the page. Unless otherwise stated, don't configure the nodes, and use only the default values. | 5. Drag the following nodes from the Components panel into the Page node: * [Platform Username](https://docs.pingidentity.com/auth-node-ref/latest/auth-node-platform-username.html) node to prompt the user to enter their username. * [Platform Password](https://docs.pingidentity.com/auth-node-ref/latest/auth-node-platform-password.html) node to prompt the user to enter their password. 6. Connect the nodes as follows and save the journey: ![A journey that can be used to authenticate an agent to PingOne Advanced Identity Cloud.](../_images/agenttree-idc.png) ## Register a PingGateway agent in PingOne Advanced Identity Cloud This procedure registers an agent profile for PingGateway. 1. Log in to the Advanced Identity Cloud admin UI as an administrator. 2. Click [icon: verified_user, set=material, size=inline] Gateways & Agents > [icon: plus, set=fa]New Gateway/Agent > Identity Gateway > Next and use the hints in the following table to create the agent profile: | Field | Description | Example | | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | ID | Set the unique agent profile name PingGateway uses to connect. | `ig_agent` | | Password | Store the password PingGateway uses to connect in the agent profile.Record the password to use when configuring PingGateway. | A strong password.The examples in the documentation use `password` and its base64-encoding `cGFzc3dvcmQ=`. | | Use Secret Store for password | Store the password in a secret and reference the secret by its label.Follow the steps in [Use the secret store for the password](#idc-use-the-secret-store-for-the-password) after you create the agent profile. | Click to enable | | Secret Label Identifier | This field appears when you select Use Secret Store for password.This value represents the `identifier` part of the secret label for the agent. PingOne Advanced Identity Cloud uses the identifier to generate a secret label in the following format: `am.application.agents.identifier.secret`. Learn more in [Secret labels](https://docs.pingidentity.com/pingoneaic/latest/tenants/esvs-signing-encryption.html#secret-labels).After setting this, add an ESV secret for the password and map the ESV to the secret label. | `ig` | | | | | - | ----------------------------------------------------------------------------------------------------------------- | | | Use secure passwords in a production environment. Consider using a password manager to generate secure passwords. | 3. Click Save Profile > Done to display the new agent profile. 4. (Optional) Add the list of Redirect URLs used in PingGateway routes and click Save to update the profile. ### Use the secret store for the password When you select Use Secret Store for password and set a secret label for the agent profile, PingOne Advanced Identity Cloud creates the secret label but the secret isn't yet defined or mapped to the label: 1. Define an ESV secret, such as `esv-ig_agent`, holding the password for PingGateway to connect. The examples in the documentation use `password`. Learn how in [creating ESV secrets](https://docs.pingidentity.com/pingoneaic/latest/tenants/esvs-manage-ui.html#create_secrets). In production deployments, [restrict access to the password](https://docs.pingidentity.com/pingoneaic/latest/tenants/esvs.html#control-access-to-secrets) from configuration placeholder and script contexts. 2. Map the ESV to the label created when you set the Secret Label Identifier: 1. Click [icon: open_in_new, set=material, size=inline] Native Consoles > Access Management > Secret Stores > ESV > Mappings > [icon: plus, set=fa]Add mappings. 2. In the Add Mapping modal, select the label, such as `am.application.agents.ig.secret`, in the Secret Label list. 3. In the aliases field, enter the ESV secret, such as `esv-ig_agent`, and click Add. 4. Click Create to add the mapping: ![agent password mapping](_images/agent-password-mapping.png) Learn more in [Map ESV secrets to secret labels](https://docs.pingidentity.com/pingoneaic/latest/tenants/esvs-signing-encryption.html#map-esv-secrets-to-secret-labels). Note the following points: * If you update or delete the Secret Label Identifier, AM updates or deletes the corresponding mapping for the previous identifier unless another agent shares the mapping. * When you rotate a secret, update the corresponding mapping. ### Optional settings In the AM admin UI, consider the following additional optional settings for the agent profile under Applications > Agents > Identity Gateway > *agent ID*: 1. To direct login to a custom URL instead of the default AM login page, configure Login URL Template for CDSSO. 2. To apply a different introspection scope, click Token Introspection and select a scope from the list. 3. Click Save to update the profile. ## Set up a demo user in PingOne Advanced Identity Cloud This procedure sets up a demo user in the alpha realm. 1. Log in to the Advanced Identity Cloud admin UI as an administrator. 2. Go to [icon: group, set=material, size=inline] Identities > Manage > [icon: settings_system_daydream, set=material, size=inline] Alpha realm - Users, and add a user with the following values: * Username: `demo` * First name: `demo` * Last name: `user` * Email Address: `demo@example.com` * Password: `Ch4ng3!t` ## Recommendations Use PingGateway with PingOne Advanced Identity Cloud as you would with any other service. * During updates, individual PingOne Advanced Identity Cloud tenant servers go offline temporarily. PingGateway can receive HTTP 502 Bad Gateway responses for some requests during the update. In your [ClientHandler](../reference/ClientHandler.html) and [ReverseProxyHandler](../reference/ReverseProxyHandler.html) configurations, configure PingGateway to retry operations when this occurs: ```json "retries": { "enabled": true, "condition": "${response.status.code == 502}" } ``` * Update PingGateway to use the latest version you can to benefit from fixes and improvements.