--- title: PingGateway guide description: This guide shows you how to set up examples that use PingGateway. It is for access management designers and administrators who develop, build, deploy, and maintain PingGateway for their organizations. component: pinggateway version: 2026 page_id: pinggateway:gateway-guide:preface canonical_url: https://docs.pingidentity.com/pinggateway/2026/gateway-guide/preface.html revdate: 2026-01-07 keywords: ["Configuration", "JSON", "Public Key Infrastructure (PKI)", "OAuth 2.0", "SAML 2.0", "Java", "Agents", "Journeys", "Data Store", "Authentication", "Nodes & Trees", "Users"] page_aliases: ["index.adoc"] section_ids: preface-examples: Example installation for this guide setup-am: Set up AM authenticate-agent-am: About authentication to AM register-agent-am: Register PingGateway with AM setup-user-am: Set up a demo user in AM am-session-cookie: Find the AM session cookie name preface-tools: External tools used in this guide --- # PingGateway guide This guide shows you how to set up examples that use PingGateway. It is for access management designers and administrators who develop, build, deploy, and maintain PingGateway for their organizations. This guide assumes familiarity with the following topics: * Hypertext Transfer Protocol (HTTP), including how clients and servers exchange messages, and the role that a reverse proxy (gateway) plays * JavaScript Object Notation (JSON), which is the format for PingGateway configuration files * Managing services on operating systems and application servers * Configuring network connections on operating systems * Managing Public Key Infrastructure (PKI) used to establish HTTPS connections * Access management for web applications Depending on the features you use, you should also have basic familiarity with the following topics: * Structured Query Language (SQL) if you use PingGateway with relational databases * Configuring AM if you use password capture and replay, or if you plan to follow the OAuth 2.0 or SAML 2.0 tutorials * The Groovy programming language if you plan to extend PingGateway with scripts * The Java programming language if you plan to extend PingGateway with plugins, and Apache Maven for building plugins ## Example installation for this guide Unless otherwise stated, the examples in this guide assume the following installation: * PingGateway accessible on `http://ig.example.com:8080` and `https://ig.example.com:8443`, as described in [Getting started with PingGateway](../getting-started/preface.html). * 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). * AM installed on http\://am.example.com:8088/openam, with the default configuration and test keys. If you use a different configuration, substitute in the procedures accordingly. ## Set up AM This section helps you prepare to use PingGateway with AM. ### About authentication to AM Unless you upgrade from an earlier version using the file-based configuration, AM 8 and later provide an [authentication journey](https://docs.pingidentity.com/pingam/8.1/am-authentication/auth-nodes-and-journeys.html) called `Agent`. The `Agent` tree validates the agent credentials with an [Agent Data Store Decision](https://docs.pingidentity.com/auth-node-ref/8.1/auth-node-agent-data-store-decision.html) node. All PingGateway, Java agent, and Web agent profiles use the `Agent` tree. Don't change its configuration. For AM 7.3 and later, when AM is [installed with a default configuration](https://docs.pingidentity.com/pingam/8.1/evaluation/preface.html), PingGateway authenticates to AM with a tree. Otherwise, PingGateway authenticates to AM with an AM authentication module. AM 7 deprecated authentication chains and modules and AM 8 removed support for them. ### Register PingGateway with AM Follow these steps to register an PingAM agent that acts on behalf of PingGateway. 1. In the AM admin UI, select the top-level realm, and then select Applications > Agents > Identity Gateway. 2. Add an agent with the following configuration, leaving other options blank or with the default value: * For SSO * For CDSSO - Agent ID : `ig_agent` - Password : `password` * Agent ID : `ig_agent` * Password : `password` * Redirect URL for CDSSO : `https://ig.ext.com:8443/home/cdsso/redirect` * Login URL Template for CDSSO: Configure this property to direct login to a custom URL instead of the default AM login page. 3. (Optional - From AM 7.5) Use AM's secret service to manage the agent profile password. If AM finds a matching secret in a secret store, it uses that secret instead of a password in the agent profile. 1. In the agent profile page, set a label for the agent password in Secret Label Identifier. AM uses the identifier to generate a secret label for the agent. The secret label has the format `am.application.agents.identifier.secret`, where identifier is the Secret Label Identifier. The Secret Label Identifier can contain only characters `a-z`, `A-Z`, `0-9`, and periods (`.`). It can't start or end with a period. 2. Select [icon: eye-slash, set=fa]Secret Stores and configure a secret store. 3. Map the label to the secret. Learn more from AM's [mapping](https://docs.pingidentity.com/pingam/8.1/security/secret-mapping.html). Note the following points for using AM's secret service: * Set a Secret Label Identifier that clearly identifies the agent. * If you update or delete the Secret Label Identifier, AM updates or deletes the corresponding mapping for the previous identifier provided no other agent shares the mapping. * When you rotate a secret, update the corresponding mapping. ### Set up a demo user in AM AM is provided with a demo user in the top-level realm, with the following credentials: * ID/username: `demo` * Last name: `user` * Password: `Ch4ng31t` * Email address: `demo@example.com` * Employee number: `123` Learn more about managing identities in AM's [Identity stores](https://docs.pingidentity.com/pingam/8.1/setup/setting-up-identity-stores.html) documentation. ### Find the AM session cookie name In routes that use an AmService, PingGateway retrieves AM's SSO cookie name from the `ssoTokenHeader` property or from AM's `/serverinfo/*` endpoint. In other circumstances where you need to find the SSO cookie name, access `http://am-base-url/serverinfo/*`. For example, access the AM endpoint with `curl`: ```console $ curl http://am.example.com:8088/openam/json/serverinfo/* ``` ## External tools used in this guide The examples in this guide use some of the following third-party tools: * `curl`: * `HTTPie`: * `jq`: * `keytool`: