--- title: Password replay and PingOne Advanced Identity Cloud description: Configure PingGateway to capture and replay user credentials to legacy web applications using a PingOne Advanced Identity Cloud journey and shared secret key component: pinggateway version: 2026 page_id: pinggateway:aic:password-replay canonical_url: https://docs.pingidentity.com/pinggateway/2026/aic/password-replay.html revdate: 2026-02-16T12:00:00Z keywords: ["Configuration", "Authentication", "Single sign-on (SSO)", "Cross Domain SSO (CDSSO)", "Nodes & Trees", "Password"] page_aliases: ["identity-cloud-guide:password-replay.adoc"] section_ids: request_flow: Request flow tasks: Tasks before_you_begin: Before you begin task_1_run_the_sample_application: "Task 1: Run the sample application" task_2_install_pinggateway: "Task 2: Install PingGateway" task_3_register_pinggateway_with_pingone_advanced_identity_cloud: "Task 3: Register PingGateway with PingOne Advanced Identity Cloud" task_4_prepare_a_shared_secret: "Task 4: Prepare a shared secret" task_5_prepare_pingone_advanced_identity_cloud: "Task 5: Prepare PingOne Advanced Identity Cloud" pwd-replay-config-gateway: "Task 6: Configure PingGateway" task_7_create_a_test_user_in_pingone_advanced_identity_cloud: "Task 7: Create a test user in PingOne Advanced Identity Cloud" validation: Validation --- # Password replay and PingOne Advanced Identity Cloud Password replay brings single sign-on (SSO) to legacy web applications without the need to edit, upgrade, or recode them. Use PingGateway with an appropriate PingOne Advanced Identity Cloud journey to capture and replay username password credentials. PingGateway and PingOne Advanced Identity Cloud share a secret key to encrypt and decrypt the password and keep it safe. When running AM in a self-hosted deployment, read [Password replay with AM](../gateway-guide/credentials-am.html). ## Request flow ![Replay a user's password to access a protected application.](_images/password-replay.svg)Figure 1. Password replay sequence diagram * PingGateway intercepts the browser's HTTP GET request. * PingGateway redirects the user to the appropriate PingOne Advanced Identity Cloud journey for authentication. * PingOne Advanced Identity Cloud authenticates the user and stores the encrypted password in a JWT. * PingOne Advanced Identity Cloud redirects the browser back to the protected application with the JWT. * PingGateway intercepts the browser's HTTP GET request again: * The user is authenticated. * PingGateway gets the password from the JWT and decrypts it. * PingGateway gets the username from PingOne Advanced Identity Cloud based on the user `_id`. * PingGateway replaces the request with an HTTP POST to the application, taking the credentials from the context. * The sample application validates the credentials from the HTTP POST request. * The sample application responds with the user's profile page. * PingGateway passes the response from the sample application to the browser. ## Tasks ### Before you begin * Make sure you can access the PingOne Advanced Identity Cloud tenant as an administrator. * Choose the realm to use in the PingOne Advanced Identity Cloud tenant. The following tasks use the `alpha` realm. * [Prepare hostnames](../getting-started/prepare-network.html) for PingGateway and the sample application. The following tasks use `ig.example.com` for PingGateway and `app.example.com` for the sample application. ### Task 1: Run the sample application 1. [Download the sample application](../getting-started/start-sampleapp.html#start-sampleapp-download). 2. Open a command-line window and [start the sample application](../getting-started/start-sampleapp.html#start-sampleapp-start): ```console $ java -jar PingGateway-sample-application-2026.3.0.jar ``` The sample application runs in the foreground until you stop it. ### Task 2: Install PingGateway This task installs PingGateway, but doesn't configure it for password replay yet. 1. [Download and unpack PingGateway](../getting-started/download-product.html). 2. [Configure PingGateway for HTTPS](../installation-guide/securing-connections.html#server-side-tls). 3. [Configure PingGateway to trust the sample application for HTTPS](../getting-started/start-sampleapp.html#sampleapp-trust) and access sample application static resources. 4. Set a top-level `session` property in `config.json` alongside the `heap` and `connections`: ```none "session": { "type": "InMemorySessionManager", "config": { "cookie": { "sameSite": "none", "secure": true } } } ``` PingOne Advanced Identity Cloud prompts the browser to send a session cookie on successful authentication. * When `sameSite` is `strict` or `lax`, the browser doesn't send the session cookie with the nonce used in validation. If PingGateway doesn't find the nonce, it assumes that the authentication failed. * When `secure` is `false`, the browser is likely to reject the session cookie. Restart PingGateway to read the updated configuration. 5. Add the following route to PingGateway: * Linux `$HOME/.openig/config/routes/01-static.json` * Windows `%appdata%\OpenIG\config\routes\01-static.json` ```json { "handler": { "type": "Chain", "config": { "filters": [ { "type": "StaticRequestFilter", "config": { "method": "POST", "uri": "https://app.example.com:8444/login", "form": { "username": [ "demo" ], "password": [ "Ch4ng31t" ] } } } ], "handler": "ReverseProxyHandler" } }, "condition": "${find(request.uri.path, '^/static')}" } ``` Source: [01-static.json](../_attachments/config/routes/01-static.json) Notice the following features of the route: * The route matches requests to `/static`. * The StaticRequestFilter replaces the request with an HTTP POST, specifying the resource to post the request to, and a form to include in the request. The form includes credentials for the username `demo`. * The ReverseProxyHandler replays the request to the sample application. 6. Verify sample application access through PingGateway by browsing . You might have used a self-signed certificate for the PingGateway HTTPS configuration. If your browser doesn't recognize the PingGateway certificate and flags it as a security risk, choose to continue. PingGateway displays a basic profile page for the `demo` user. PingGateway now has the configuration required as a basis on which to build password replay. ### Task 3: Register PingGateway with PingOne Advanced Identity Cloud If you haven't yet registered PingGateway with PingOne Advanced Identity Cloud, follow these steps: 1. [Configure an `Agent` journey](preface.html#authenticate-agent-idc) PingGateway uses to authenticate with PingOne Advanced Identity Cloud. 2. [Register a profile for PingGateway](preface.html#register-agent-idc). | Field | Value | Description | | ------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | ID | `ig_agent` | The PingGateway username when connecting to the `AmService` in PingOne Advanced Identity Cloud. | | Password | `password` | The PingGateway password when connecting to the `AmService` in PingOne Advanced Identity Cloud.In production tenants, use a strong password. | | Redirect URLs | `https://ig.example.com:8443/replay/redirect` | The PingGateway endpoint to process the encrypted JWT from PingOne Advanced Identity Cloud. | PingOne Advanced Identity Cloud is now ready for PingGateway to connect. You'll share the credentials with PingGateway in [Task 6: Configure PingGateway](#pwd-replay-config-gateway). ### Task 4: Prepare a shared secret PingGateway and Advanced Identity Cloud share a secret symmetric key to encrypt and decrypt the password. The Advanced Identity Cloud authentication journey you will configure includes the JWT Password Replay node to capture the password in an encrypted JWT it sends to PingGateway. The JWT Password Replay node relies on a secret label of the form `am.authentication.nodes.jwt.replay.identifier.encryption` to get the shared secret key. This example uses `pinggateway` as the *identifier* and stores is as an ESV secret. PingGateway stores the secret in a PEM file, so the following steps do that first: 1. Create a `secrets` folder next to the PingGateway instance folder to store the shared secret key: ```console $ mkdir secrets ``` 2. Generate a base64-encoded shared secret using the filename the JWT Password Replay node requires: ```console $ echo "-----BEGIN AES SECRET KEY-----" > secrets/am.authentication.nodes.jwt.replay.pinggateway.encryption $ head -c32 /dev/urandom | base64 >> secrets/am.authentication.nodes.jwt.replay.pinggateway.encryption $ echo "-----END AES SECRET KEY-----" >> secrets/am.authentication.nodes.jwt.replay.pinggateway.encryption ``` The file contains the base64-encoded shared secret in PEM format. 3. Store the shared secret key as an ESV in PingOne Advanced Identity Cloud. 1. Sign on to the Advanced Identity Cloud admin UI as an administrator and go to [icon: cog, set=fa]Tenant Settings > Global Settings > Environment Secrets & Variables. 2. Click Secrets > + Add Secret. 3. In the Add a Secret modal, enter the following settings: | Field | Value | Description | | ----- | ---------------------------------------------- | ------------------------------------------ | | Name | `esv-password-replay-shared-secret` | The ESV name for the secret. | | Value | Base64-encoded shared secret from the PEM file | The base64-encoded random AES 256-bit key. | 4. Click Save to create the variable. PingOne Advanced Identity Cloud can now access the secret through the ESV secret. PingGateway will use the secret in the local PEM file in [Task 6: Configure PingGateway](#pwd-replay-config-gateway). You have successfully prepared the shared secret for Advanced Identity Cloud and PingGateway. ### Task 5: Prepare PingOne Advanced Identity Cloud Update the PingOne Advanced Identity Cloud validation service for PingGateway and add a journey to use the script and a mapping for the secret. 1. Sign on to the Advanced Identity Cloud admin UI as an administrator and go to [icon: open_in_new, set=material, size=inline] Native Consoles > Access Management, select Services, and the following Valid goto URL Resources to the Validation Service: * `https://ig.example.com:8443/*` * `https://ig.example.com:8443/*?*` 2. Go to Journeys, click + New Journey, and create a journey named `Password replay` whose Identity Object is `managed/alpha_user`. 3. Configure and save the journey with the nodes shown in this screenshot: ![Password replay journey](_images/password-replay-journey.png) * The Page node presents a page with input fields to prompt for the username and password. * The Platform Username node collects and injects the `userName` into the shared node state. * The Platform Password node collects and injects the `password` into the shared node state. * The Identity Store Decision node uses the username and password to determine whether authentication is successful. * The JWT Password Replay node stores the password in a JWT encrypted with the shared secret key. Its Encryption Key Secret Label Identifier is `pinggateway`. 4. In the AM admin UI, go to Secret Stores > ESV > Mappings and add the following mapping to let the JWT Password Replay node access the shared secret: * Secret Label `am.authentication.nodes.jwt.replay.pinggateway.encryption` * Active Alias `esv-password-replay-shared-secret` Make sure you save the mapping. 5. In your browser's privacy or incognito mode, go to the new journey and make sure you can sign on with the credentials of a known user. PingOne Advanced Identity Cloud authenticates you and displays the user profile page. You have successfully prepared the journey and can now configure PingGateway to replay the password. ### Task 6: Configure PingGateway The password replay configuration ensures PingGateway can connect to PingOne Advanced Identity Cloud, get the shared secret to decode the JWT with the password, and replay the credentials to the sample application. 1. Set an environment variable locally on the computer running PingGateway to access the base64-encoded agent password: ```console $ export AGENT_SECRET_ID='cGFzc3dvcmQ=' ``` PingGateway retrieves the password with a [SystemAndEnvSecretStore](../reference/SystemAndEnvSecretStore.html), which requires it to be base64-encoded. The password must match the agent profile password you set in PingOne Advanced Identity Cloud. PingGateway uses the password to connect to PingOne Advanced Identity Cloud. 2. Add a route to PingGateway to serve the sample application .css and other static resources if you haven't already: * Linux `$HOME/.openig/config/routes/00-static-resources.json` * Windows `%appdata%\OpenIG\config\routes\00-static-resources.json` > **Collapse: Show route** > > ```json > { > "name" : "00-static-resources", > "baseURI" : "https://app.example.com:8444", > "condition": "${find(request.uri.path,'^/css') or matchesWithRegex(request.uri.path, '^/.*\\\\.ico$') or matchesWithRegex(request.uri.path, '^/.*\\\\.gif$')}", > "handler": "ReverseProxyHandler" > } > ``` Source: [00-static-resources.json](../_attachments/config/routes/00-static-resources.json) This route correctly sets the content types for the static resources used by the sample application. 3. Add a route for password replay. * Linux `$HOME/.openig/config/routes/04-replay-aic.json` * Windows `%appdata%\OpenIG\config\routes\04-replay-aic.json` > **Collapse: Show route** > > ```json > { > "name": "04-replay-aic", > "condition": "${find(request.uri.path, '^/replay')}", > "properties": { > "amInstanceUrl": "https://myTenant.forgeblocks.com/am/" > }, > "heap": [ > { > "name": "SystemAndEnvSecretStore-1", > "type": "SystemAndEnvSecretStore" > }, > { > "name": "AmService-1", > "type": "AmService", > "config": { > "url": "&{amInstanceUrl}", > "realm": "/alpha", > "agent": { > "username": "ig_agent", > "passwordSecretId": "agent.secret.id" > }, > "secretsProvider": "SystemAndEnvSecretStore-1" > }, > "sessionCache": { > "enabled": false > } > }, > { > "name": "PemPropertyFormat-1", > "type": "PemPropertyFormat" > }, > { > "name": "FileSystemSecretStore-1", > "type": "FileSystemSecretStore", > "config": { > "format": "PLAIN", > "directory": "&{ig.instance.dir}/../secrets/", > "mappings": [ > { > "secretId": "am.authentication.nodes.jwt.replay.pinggateway.encryption", > "format": "PemPropertyFormat-1" > } > ] > } > }, > { > "name": "CapturedUserPasswordFilter-1", > "type": "CapturedUserPasswordFilter", > "config": { > "ssoToken": "${contexts.ssoToken.value}", > "keySecretId": "am.authentication.nodes.jwt.replay.pinggateway.encryption", > "secretsProvider": "FileSystemSecretStore-1", > "amService": "AmService-1" > } > } > ], > "handler": { > "type": "Chain", > "config": { > "filters": [ > { > "name": "CrossDomainSingleSignOnFilter-1", > "type": "CrossDomainSingleSignOnFilter", > "config": { > "redirectEndpoint": "/replay/redirect", > "authCookie": { > "path": "/replay", > "name": "ig-token-cookie" > }, > "amService": "AmService-1", > "authenticationService": "Password replay" > } > }, > { > "name": "UserProfileFilter-1", > "type": "UserProfileFilter", > "config": { > "username": "${contexts.ssoToken.info.uid}", > "userProfileService": { > "type": "UserProfileService", > "config": { > "amService": "AmService-1", > "profileAttributes": [ > "username" > ] > } > } > } > }, > { > "name": "PasswordReplayFilter-1", > "type": "PasswordReplayFilter", > "config": { > "loginPage": "${true}", > "credentials": "CapturedUserPasswordFilter-1", > "request": { > "method": "POST", > "uri": "https://app.example.com:8444/login", > "form": { > "username": [ > "${contexts.userProfile.username}" > ], > "password": [ > "${contexts.capturedPassword.value}" > ] > } > } > }, > "capture": [ > "all" > ] > } > ], > "handler": "ReverseProxyHandler" > } > } > } > ``` Source: [04-replay-aic.json](../_attachments/config/routes/04-replay-aic.json). The route: * Matches requests whose path starts with `/replay`. * Sets an `amInstanceUrl` property to the access management service in PingOne Advanced Identity Cloud. Update the URL to target your tenant. * Connects to PingOne Advanced Identity Cloud as `ig_agent` with the `agent.secret.id` password from the local `AGENT_SECRET_ID` environment variable. * Loads the `am.authentication.nodes.jwt.replay.pinggateway.encryption` shared secret key from the PEM file. Make sure you're using the shared secret key you stored in the PingOne Advanced Identity Cloud ESV. PingOne Advanced Identity Cloud uses the secret key to encrypt the password to replay. PingGateway uses the secret key to decrypt the password to replay. * Extracts the captured password from the SSO token context and decrypts it with the shared secret key. * Uses a [CrossDomainSingleSignOnFilter](../reference/CrossDomainSingleSignOnFilter.html) to redirect to the PingOne Advanced Identity Cloud `Password replay` journey for authentication, getting the authentication information from the `ig-token-cookie`. * Queries the access management service in PingOne Advanced Identity Cloud to retrieve the username for signing on. You can retrieve other profile attributes with the [UserProfileFilter](../reference/UserProfileFilter.html), such as the email address or first and last names. The sample application expects the username in this example, so the route gets the username. * Signs on to the sample application with the username and password. * Returns the result to the browser. In production, remove `"capture": ["all"]` from the [PasswordReplayFilter](../reference/PasswordReplayFilter.html) to avoid recording credentials in the logs. 4. Restart PingGateway to read the secrets and load the new route. In the PingGateway output, make sure the route loaded successfully with no errors or warnings: `@system - Loaded the route with id '04-replay-aic' registered with the name '04-replay-aic'`. You have successfully configured PingGateway to replay the password. ### Task 7: Create a test user in PingOne Advanced Identity Cloud The sample application validates the credentials for password replay. It must recognize the username and password you use. The sample application has built-in username-password combinations. The username and password credentials shown in the following steps are one of the built-in pairs. 1. In your browser's privacy or incognito mode, go to the default login journey for the realm you're using. For example, `https://myTenant.forgeblocks.com/am/XUI/?realm=/alpha#/`. 2. Click the Create an account link and enter the following settings in the Sign Up page: | Field | Value | | -------------------------- | -------------------------------------------------------------------------------------- | | Username | `wolkig` | | First name | `Wilhelm` | | Last name | `Wolkig` | | Email Address | Your email. PingOne Advanced Identity Cloud sends a confirmation mail to this address. | | Password | `Geh3imnis!` | | Select a security question | `What's your favorite color?` | | Answer | `Red` | 3. Click Next to complete account creation and view the user profile. 4. Sign off. You have successfully created a test user in PingOne Advanced Identity Cloud with credentials the sample application recognizes. ## Validation 1. In your browser's privacy or incognito mode, go to . PingGateway redirects to the PingOne Advanced Identity Cloud journey. 2. Sign on as user `wolkig` with password `Geh3imnis!`. PingGateway successfully replays the credentials against the sample application. The sample application displays its user profile page: ![Successful password replay](_images/password-replay-success.png) 3. Review the PingGateway output. On success, the output displays the credentials and the profile page: ```none ...INFO o.f.o.d.c.C.c.PasswordReplayFilter-1 @04-replay-aic - [CONTINUED]--- (filtered-request) exchangeId: - transactionId: ---> [CONTINUED]POST https://app.example.com:8444/login HTTP/1.1 ... [CONTINUED]password=Geh3imnis%21&username=wolkig ...INFO o.f.o.d.c.C.c.PasswordReplayFilter-1 @04-replay-aic - [CONTINUED]<--- (response) exchangeId: - transactionId: --- [CONTINUED]HTTP/1.1 200 OK ... [CONTINUED] ... ``` You have successfully demonstrated password replay with PingGateway and PingOne Advanced Identity Cloud. If password replay fails, consider the outcome of the HTTP POST from PingGateway to the sample application: * HTTP 401 Unauthorized PingGateway isn't replaying the credentials. Review the PingGateway output to determine whether the username or password is missing when PingGateway replays the credentials. If the password is missing, make sure PingGateway and PingOne Advanced Identity Cloud share the same AES secret key. * HTTP 403 Forbidden PingGateway isn't replaying the right credentials. Make sure you're using a username-password combination known to the sample application.