Using the sample application

Ping Identity provides a mockup web application for testing PingGateway configurations. The sample application is used in the examples throughout the PingGateway documentation.

Download the sample application

Download PingGateway-sample-application-2025.11.0-jar-with-dependencies.jar, from the Ping Identity Download Center.

Start the sample application

Start the sample application:
$ java -jar PingGateway-sample-application-2025.11.0-jar-with-dependencies.jar
Output
... [...] [INFO ] Press Ctrl+C to stop the server.
(Optional) port numbers

By default, this server listens for HTTP on port 8081 and for HTTPS on port 8444. If one or both of those ports aren’t free, specify other ports:
$ java -jar PingGateway-sample-application-2025.11.0-jar-with-dependencies.jar 8888 8889
(Optional) OpenTelemetry support

By default, OpenTelemetry support is disabled in the sample application. To enable it, set OTEL_SDK_DISABLED=false when starting the sample application:
$ OTEL_SDK_DISABLED=false java -jar PingGateway-sample-application-2025.11.0-jar-with-dependencies.jar
The tracing configuration for the sample application uses automatic configuration. For example, to enable OpenTelemetry support and publish to a remote service:
$ OTEL_SDK_DISABLED=false \ OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://exporter.example.com:1234/traces \ java -jar PingGateway-sample-application-2025.11.0-jar-with-dependencies.jar
Learn more about configuration options in the OpenTelemetry documentation on automatic configuration. The sample application supports only http/protobuf for the exporter protocol.
Check that the sample application responds to requests in one of the following ways:
- In your browser’s privacy or incognito mode, go to https://app.example.com:8444/home to access the home page of the sample application and accept the self-signed certificate.
  
  The browser displays information about the request.
- In your browser’s privacy or incognito mode, go to https://app.example.com:8444/login to access the login page of the sample application, accept the self-signed certificate, and sign on with username demo and password Ch4ng31t.
  
  The browser displays the username and information about the request.

Trust the sample application

The sample application uses a self-signed TLS certificate for HTTPS. Browsers and HTTP clients like PingGateway won’t connect as they don’t trust self-signed certificates. You must explicitly trust the sample application certificate.

In the browser, this means accepting the risk and adding an exception for the self-signed certificate. In client applications like PingGateway, this means getting the sample application certificate and configuring the client to trust it:

Get the sample application certificate in one of the following ways:
- Download the sampleapp.cert.pem file and save it in a tls folder.
- Extract it from the PingGateway-sample-application-2025.11.0-jar-with-dependencies.jar file:
  $ jar --verbose --extract --file PingGateway-sample-application-2025.11.0-jar-with-dependencies.jar tls/sampleapp.cert.pem
  The command extracts the certificate to tls/sampleapp.cert.pem in the current directory.

Start the sample application and check the certificate’s trusted for an HTTPS request:

$ curl --head --cacert tls/sampleapp.cert.pem --url https://app.example.com:8444/home

Output

HTTP/2 200

Move or copy the tls directory containing the certificate under the PingGateway directory:

Linux

$HOME/.openig/tls/sampleapp.cert.pem

Windows

%appdata%\OpenIG\tls\sampleapp.cert.pem

Configure PingGateway to trust the sample application certificate when acting as a reverse proxy.

Add the following as config.json in the PingGateway configuration directory:

Linux: $HOME/.openig/config/config.json
Windows: %appdata%\OpenIG\config\config.json

{
  "handler": {
    "type": "Router",
    "name": "_router",
    "config": {
      "directory": "${openig.configDirectory}/routes"
    }
  },
  "heap": [
    {
      "name": "capture",
      "type": "CaptureDecorator",
      "config": {
        "captureEntity": true,
        "_captureContext": true
      }
    },
    {
      "name": "ClientTlsOptions",
      "type": "ClientTlsOptions",
      "config": {
        "trustManager": {
          "type": "SecretsTrustManager",
          "config": {
            "certificateVerificationSecretId": "sampleapp.cert",
            "secretsProvider": {
              "type": "FileSystemSecretStore",
              "config": {
                "directory": "&{ig.instance.dir}/tls",
                "format": "PLAIN",
                "suffix": ".pem",
                "mappings": [
                  {
                    "secretId": "sampleapp.cert",
                    "format": {
                      "type": "PemPropertyFormat"
                    }
                  }
                ]
              }
            }
          }
        }
      }
    },
    {
      "name": "ReverseProxyHandler",
      "type": "ReverseProxyHandler",
      "config": {
        "tls": "ClientTlsOptions"
      }
    }
  ],
  "session": {
    "type": "JwtSessionManager"
  }
}

Source: config.json

Restart PingGateway to pick up the change.

Add a route to PingGateway to serve the sample application static resources that don’t need protection:

Linux: $HOME/.openig/config/routes/00-static-resources.json
Windows: %appdata%\OpenIG\config\routes\00-static-resources.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

Optionally check PingGateway trusts the sample application:

Add a route for the sample application to PingGateway:
Linux

$HOME/.openig/config/routes/00-home.json

Windows

%appdata%\OpenIG\config\routes\00-home.json
{ "name": "00-home", "condition": "${find(request.uri.path, '^/home')}", "baseURI": "https://app.example.com:8444", "handler": "ReverseProxyHandler" }
Source: 00-home.json
Go to https://ig.example.com:8080/home to access the home page of the sample application.

The browser displays information about the request.

Stop the sample application

In the terminal where the sample application is running, enter CTRL+C to stop the sample application.

Configuration options

To view the command-line options for the sample application, start it with the -h option:

$ java -jar PingGateway-sample-application-2025.11.0-jar-with-dependencies.jar -h

Output

Usage: <main class> [options]
  Options:
    --http
      The HTTP port number.
      Default: 8081
    --https
      The HTTPS port number.
      Default: 8444
    --session
      The session timeout in seconds.
      Default: 60
    --am-discovery-url
      The AM URL base for OpenID Provider Configuration.
      Default: http://openam.example.com:8088/openam/oauth2
    --latency
      The simulated request latency in seconds.
      Default: 2
    --latency-requests-frequency
      The frequency at which latency is applied to requests.
      Default: 1
    --latency-requests-chunks-count
      The number of chunks into which the request payload will be divided,
      with latency applied to each chunk.
      Default: 1
    -h, --help
      Default: false