--- title: PingGateway and PingOne Advanced Identity Cloud description: Integrate PingGateway with PingOne Advanced Identity Cloud for SSO and API security. Covers example setup, agent authentication, registration, and demo users. component: pinggateway version: 2026 page_id: pinggateway:aic:preface canonical_url: https://docs.pingidentity.com/pinggateway/2026/aic/preface.html revdate: 2025-10-15T18:45:22Z keywords: ["Single sign-on (SSO)", "Security", "URI", "Authenticate", "Agents", "Journeys", "Nodes & Trees"] page_aliases: ["aic:index.adoc", "identity-cloud-guide:index.adoc", "identity-cloud-guide:preface.adoc"] section_ids: preface-examples: Example installation authenticate-agent-idc: About authentication 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 an ESV for the password optional_settings: Optional settings setup-user-idc: Set up a demo user in PingOne Advanced Identity Cloud idc-recommendations: Recommendations --- # PingGateway and PingOne Advanced Identity Cloud These pages show how to use PingGateway with PingOne Advanced Identity Cloud for single sign-on and API security. They're for PingOne Advanced Identity Cloud evaluators, administrators, and architects. ## Example installation Unless otherwise stated, the examples with PingOne Advanced Identity Cloud assume the following installation: * PingGateway listening at `http://ig.example.com:8080`. Learn more in [Installing PingGateway](../installation-guide/preface.html). * The sample application listening at `https://app.example.com:8444` with PingGateway trusting it for HTTPS and ready to serve static resources. Learn more in [Using the sample application](../getting-started/start-sampleapp.html). * A PingOne Advanced Identity Cloud tenant with the default configuration. Learn more in the [PingOne Advanced Identity Cloud documentation](https://docs.pingidentity.com/pingoneaic/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 PingOne Advanced Identity Cloud tenant root URL 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. ## About authentication to PingOne Advanced Identity Cloud PingOne Advanced Identity Cloud provides an authentication journey to validate the agent credentials with an Agent Data Store Decision node. When you register PingGateway with PingOne Advanced Identity Cloud, PingOne Advanced Identity Cloud uses the journey to authenticate PingGateway. ## Register a PingGateway agent in PingOne Advanced Identity Cloud This procedure registers an agent profile for PingGateway. 1. Sign on 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 | Optionally store the password in a secret and reference the secret by its label.After you create an agent profile with this option enabled, make sure you follow the steps in [Use an ESV for the password](#idc-use-the-secret-store-for-the-password). | 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/tenants/esvs-signing-encryption.html#secret-labels).After setting this, make sure you follow the steps in [Use an ESV for the password](#idc-use-the-secret-store-for-the-password). | `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. 5. Switch to the AM admin UI, go to Applications > Agents > Identity Gateway > *agent ID*, and update the Login URL Template for CDSSO. Advanced Identity Cloud doesn't set a default. Configure this property to ensure Advanced Identity Cloud notifies PingGateway on authentication failure. PingGateway uses the notification to remove stale session data. * When using the default Advanced Identity Cloud login pages, add the following template all one line, replacing \ to match your deployment: ```none https:///am/login? <#if service??>&service=${service} &goto=${goto} &gotoOnFail=${gotoOnFail} <#if acrValues??>&acr_values=${acrValues} <#if realm??>&realm=${realm} <#if module??>&module=${module} <#if locale??>&locale=${locale} ``` * When using a custom login page outside Advanced Identity Cloud, use a template matching the login page requirements. Make sure to include a `${gotoOnFail}` parameter in the template. Update the custom login page to use the new parameter, verify its value is valid to protect against open redirect attacks, and redirect the user-agent when authentication fails. ### Use an ESV 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. You must create an ESV secret for the password and map the ESV to the label: 1. Use the Advanced Identity Cloud admin UI to 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 the PingOne Advanced Identity Cloud documentation on [creating ESV secrets](https://docs.pingidentity.com/pingoneaic/tenants/esvs-manage-ui.html#create_secrets). In production deployments, [restrict access to the password](https://docs.pingidentity.com/pingoneaic/tenants/esvs.html#control-access-to-secrets) from configuration placeholder and script contexts. 2. Use the AM admin UI to 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: ![agent password mapping](_images/agent-password-mapping.png) 4. Click Create to add the mapping. Learn more in the Advanced Identity Cloud documentation on [mapping ESV secrets to secret labels](https://docs.pingidentity.com/pingoneaic/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 apply a different introspection scope, click Token Introspection and select a scope from the list. 2. 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.