Protect the deployment

This is not a comprehensive platform implementation guide. These sample setup instructions show a minimal integration of platform components to get you started.

The Ping Identity Platform offers maximum extensibility and flexibility in self-managed deployments. The platform includes many features and options these sample setup instructions do not cover. If you don’t need maximum extensibility and flexibility, there are simpler alternatives:

To consume the platform as a service, use PingOne Advanced Identity Cloud.
To deploy in Kubernetes, start with the ForgeOps reference implementation.

For help with your deployment and to validate your plans before deploying in production, contact Ping Identity.

Before you start

After you set up a sample deployment according to Separate identity stores or Shared identity store, you have a functionally complete Ping Identity Platform installation.

Your deployment still lacks key features:

Security: Except when connecting to the directory service, connections use HTTP, not HTTPS. Users send their login credentials in unprotected cleartext.
Single entry point: The Platform UI component applications don’t all run on the same host and port. This means cookies and iframes don’t always share the same host and origin, a potential problem for modern browsers.

The instructions that follow show how to add PingGateway to your deployment, providing a single point of entry to Ping Identity Platform, and securing communications from outside with HTTPS.

The following examples deploy PingGateway on platform.example.com using port 9443 for HTTPS. Adapt the examples as necessary for your deployment.

For example, if you’re demonstrating the deployment on your computer, add an alias for the fully qualified domain name to your /etc/hosts file:
```
127.0.0.1    platform.example.com
```
Before using PingGateway to protect the deployment, make sure that PingAM uses example.com as the cookie domain.

This setting ensures that your browser can share cookies across subdomains in example.com. If PingAM is using the default cookie domain, such as am.example.com, then users won’t be able to sign in through PingGateway.

You can check by logging in to the AM admin UI as amAdmin, browsing to Global Services > Platform, and verifying that Cookie Domains is set to example.com.

The instructions that follow are sufficient to add PingGateway to your sample deployment. Find in-depth documentation on using PingGateway in the PingGateway product documentation.

Prepare keys

HTTPS requires a server key pair for PingGateway.

In a public deployment where PingGateway is the entry point, get the PingGateway server certificate signed by a well-known CA. A server certificate signed by a well-known CA will be trusted by other systems and browsers, because the CA certificate is distributed with the system or the browser.

The examples that follow do not use a well-known CA. Instead, they use an PingGateway server certificate generated with one of the PingDS deployment ID and password combinations that you used to set up the deployment.

You’ll generate an PingGateway server key pair using the PingDS dskeymgr command.
You’ll export and trust the deployment ID CA certificate to demonstrate and test the deployment.

As long as no one else knows your deployment ID and password combination, this is safe, because only you have the secrets to generate this CA certificate, or to generate signed keys:

Generate the keys on a system where you installed PingDS:

Save a password file for the keystore:

mkdir -p /path/to/security/
touch /path/to/security/keystore.pin
chmod 600 /path/to/security/keystore.pin
echo -n password > /path/to/security/keystore.pin

Be sure to use echo -n, as PingGateway can’t use the secret if the file has a newline character at the end.

Set the deployment ID in an environment variable that you’ll use in dskeymgr commands:
```
export DEPLOYMENT_ID=deployment-id
```

Generate a server key pair for PingGateway to use for HTTPS:

/path/to/opendj/bin/dskeymgr \
 create-tls-key-pair \
 --deploymentId $DEPLOYMENT_ID \
 --deploymentIdPassword password \
 --keyStoreFile /path/to/security/keystore \
 --keyStorePassword:file /path/to/security/keystore.pin \
 --hostname localhost \
 --hostname platform.example.com \
 --subjectDn CN=platform.example.com,O=ForgeRock

Inspect the contents of the keystore you just created to find the key alias is ssl-key-pair:

keytool -list -keystore /path/to/security/keystore -storepass:file /path/to/security/keystore.pin
Keystore type: PKCS12
Keystore provider: SUN

Your keystore contains 1 entry

ssl-key-pair, <date>, PrivateKeyEntry,
Certificate fingerprint (SHA-256): <fingerprint>

Copy the keystore and password to the system where PingGateway runs.
Export the deployment ID CA certificate to trust:
```
/path/to/opendj/bin/dskeymgr \
export-ca-cert \
--deploymentId $DEPLOYMENT_ID \
--deploymentIdPassword password \
--outputFile ca-cert.pem
```
Use this ca-cert.pem file when you need to trust the PingGateway server certificate. You can import it into your browser to trust the platform URLs in this example.

Install PingGateway

This example uses PingGateway in standalone mode. In standalone mode, PingGateway runs in the web container provided in the .zip file.

Download PingGateway-2025.3.0.zip.
Unpack the files.

This example shows the files unpacked in the /path/to/identity-gateway-2025.3 directory.
Create a configuration directory for PingGateway:
```
mkdir -p $HOME/.openig/config/
```
The default PingGateway configuration directory is $HOME/.openig/config on Linux and UNIX, and %appdata%\OpenIG\config on Windows.

Add an admin.json configuration file for HTTPS support at the root of the PingGateway configuration directory.

Sample admin.json

This example expects the keystore and keystore.pin file in the /path/to/security/ directory:

{
    "heap": [
        {
            "name": "TlsConf",
            "type": "ServerTlsOptions",
            "config": {
                "keyManager": {
                    "type": "SecretsKeyManager",
                    "config": {
                        "signingSecretId": "key.manager.secret.id",
                        "secretsProvider": "ServerIdentityStore"
                    }
                }
            }
        },
        {
            "name": "SecretsPasswords",
            "type": "FileSystemSecretStore",
            "config": {
                "directory": "/path/to/security/",
                "format": "PLAIN"
            }
        },
        {
            "name": "ServerIdentityStore",
            "type": "KeyStoreSecretStore",
            "config": {
                "file": "/path/to/security/keystore",
                "storePasswordSecretId": "keystore.pin",
                "secretsProvider": "SecretsPasswords",
                "mappings": [
                    {
                        "secretId": "key.manager.secret.id",
                        "aliases": [
                            "ssl-key-pair"
                        ]
                    }
                ]
            }
        }
    ],
    "connectors": [
        {
            "port": 9080
        },
        {
            "port": 9443,
            "tls": "TlsConf"
        }
    ]
}

Start PingGateway:

/path/to/identity-gateway-2025.3bin/start.sh
...
[main] INFO ... started in XXXXms on ports : [9080, 9443]

Test that you can use the PingGateway "ping" endpoint over HTTP:
```
curl -v http://platform.example.com:9080/openig/ping
```
The output should include an HTTP 200 status code indicating success, and an empty reply from PingGateway.
When you can successfully ping PingGateway over HTTP, try HTTPS using your CA certificate file:
```
curl -v --cacert ca-cert.pem https://platform.example.com:9443/openig/ping
```
The ca-cert.pem file is the one you exported with the dskeymgr command. If it’s not in the current directory, include the path to the file.

As before, you should receive an empty success response. This demonstrates that you successfully connected to PingGateway over HTTPS.

Now that you’re sure the HTTPS connection works, you can edit admin.json to stop using port 9080 for HTTPS.

Trust the deployment ID certificate

You generated a deployment ID CA certificate used in this example with the dskeymgr command. Your browser doesn’t recognize this private CA until you trust it by importing the CA certificate.

Make sure this certificate is trusted when negotiating SSL and HTTPS connections.

If you don’t do this, you’ll see an error similar to the following when you attempt to access the Platform UI:

Your connection is not private
Attackers might be trying to steal your information from platform.example.com...
net::ERR_CERT_AUTHORITY_INVALID

As long as no one else knows your deployment ID and password combination, this is safe, because only you have the secrets to generate this CA certificate, or to generate signed keys:

Trust the deployment ID CA certificate by importing the ca-cert.pem file as a certificate authority trusted for SSL and HTTPS connections.

Some browsers refer to "Authorities" in the browser settings. You can find more information in your browser help.

Configure PingGateway

PingGateway terminates HTTPS for your deployment. All access to your deployment goes through PingGateway.

Configure PingGateway to route traffic through to the components of the deployment and back to clients. The settings in the following steps depend on the settings you’ll use to set up the Platform UI:

Add a config.json configuration file at the root of the PingGateway configuration directory.

Sample config.json

This example configures the capture decorator and a router with a default route:

{
    "heap": [
        {
            "name": "capture",
            "type": "CaptureDecorator"
        },
        {
            "name": "DefaultRoute",
            "type": "StaticResponseHandler",
            "config": {
                "status": 200,
                "headers": {
                    "Content-Type": [
                        "text/html"
                    ]
                },
                "entity": "<html><p><a href='/enduser-login/?realm=/alpha#/service/PlatformLogin'>End user access</a></p><p><a href='/platform-login/?realm=/#/'>Admin access</a></p></html>"
            }
        },
        {
            "type": "Router",
            "name": "_router",
            "config": {
                "defaultHandler": "DefaultRoute"
            }
        }
    ],
    "handler": "_router",
    "audit": "global"
}

The default route in the sample file defines a simple static HTML page to present when a user accesses the platform before logging in, or after logging out.

In this example, the page includes a link for each of the two user flows:

An end user logs in to access their applications and profile page through the End User UI.
An admin logs in to configure the platform through the Platform Admin UI, AM admin UI, or IDM admin UI.

You can configure PingGateway to redirect users to your site if desired. PingGateway can also serve static pages, so you can add an entry point that matches your site.

Create a routes directory under the PingGateway configuration file directory:
```
mkdir $HOME/.openig/config/routes
```

Add a login.json route file in the routes directory.

This route consumes the paths specified in the links on the default, static page to route users to the correct URL on the Login UI:

Sample login.json

{
    "name": "login",
    "condition": "${find(request.uri.path, '^/enduser-login|^/platform-login')}",
    "baseURI": "http://login.example.com:8083",
    "handler": {
        "type": "Chain",
        "config": {
            "filters": [
                {
                    "type": "UriPathRewriteFilter",
                    "config": {
                        "mappings": {
                            "/enduser-login": "/",
                            "/platform-login": "/"
                        },
                        "failureHandler": "DefaultRoute"
                    }
                }
            ],
            "handler": "ReverseProxyHandler"
        }
    }
}

Add an enduser-ui.json route file in the routes directory.

This route sends end users to the End User UI:

Sample for End User UI from a Docker image

{
    "name": "enduser-ui",
    "condition": "${find(request.uri.path, '^/enduser-ui')}",
    "baseURI": "http://enduser.example.com:8888",
    "handler": {
        "type": "Chain",
        "config": {
            "filters": [
                {
                    "type": "UriPathRewriteFilter",
                    "config": {
                        "mappings": {
                            "/enduser-ui": "/"
                        },
                        "failureHandler": "DefaultRoute"
                    }
                }
            ],
            "handler": "ReverseProxyHandler"
        }
    }
}

Sample for End User UI from a .zip file

{
    "name": "enduser-ui",
    "condition": "${find(request.uri.path, '^/enduser-ui')}",
    "baseURI": "http://am.example.com:8081",
    "handler": {
        "type": "Chain",
        "config": {
            "filters": [
                {
                    "type": "UriPathRewriteFilter",
                    "config": {
                        "mappings": {
                            "/enduser-ui": "/enduser"
                        },
                        "failureHandler": "DefaultRoute"
                    }
                }
            ],
            "handler": "ReverseProxyHandler"
        }
    }
}

Add a platform-ui.json route file in the routes directory.

This route sends administrators to the Admin UI:

Sample for Admin UI from Docker images

{
    "name": "platform-ui",
    "condition": "${find(request.uri.path, '^/platform-ui')}",
    "baseURI": "http://admin.example.com:8082",
    "handler": {
        "type": "Chain",
        "config": {
            "filters": [
                {
                    "type": "UriPathRewriteFilter",
                    "config": {
                        "mappings": {
                            "/platform-ui": "/"
                        },
                        "failureHandler": "DefaultRoute"
                    }
                }
            ],
            "handler": "ReverseProxyHandler"
        }
    }
}

Sample for Admin UI from a .zip file

{
    "name": "platform-ui",
    "condition": "${find(request.uri.path, '^/platform-ui')}",
    "baseURI": "http://am.example.com:8081",
    "handler": {
        "type": "Chain",
        "config": {
            "filters": [
                {
                    "type": "UriPathRewriteFilter",
                    "config": {
                        "mappings": {
                            "/platform-ui": "/platform"
                        },
                        "failureHandler": "DefaultRoute"
                    }
                }
            ],
            "handler": "ReverseProxyHandler"
        }
    }
}

Add an am.json route file in the routes directory.

This route handles requests to PingAM, ensuring that the browser gets redirected through PingGateway:

Sample am.json

{
    "name": "am",
    "baseURI": "http://am.example.com:8081",
    "condition": "${find(request.uri.path, '(?:^/am(?!/XUI))')}",
    "handler": {
        "type": "Chain",
        "config": {
            "filters": [
                {
                    "comment": "Always redirect to IG rather than AM",
                    "type": "LocationHeaderFilter",
                    "config": {
                        "baseURI": "https://platform.example.com:9443/"
                    }
                }
            ],
            "handler": "ReverseProxyHandler"
        }
    }
}

Add an idm.json route file in the routes directory.

This route handles requests to PingIDM, ensuring that the browser gets redirected through PingGateway:

Sample idm.json

{
    "name": "idm",
    "baseURI": "http://openidm.example.com:8080",
    "condition": "${find(request.uri.path, '(?:^/openidm)|(?:^/admin)|(?:^/upload)|(?:^/export)')}",
    "handler": {
        "type": "Chain",
        "config": {
            "filters": [
                {
                    "comment": "Always redirect to IG rather than IDM",
                    "type": "LocationHeaderFilter",
                    "config": {
                        "baseURI": "https://platform.example.com:9443/"
                    }
                }
            ],
            "handler": "ReverseProxyHandler"
        }
    }
}

Restart PingGateway to take all your changes into account.

Verify in the server output that all your routes load successfully.

When troubleshooting and developing routes, you can change an PingGateway route configuration while PingGateway is running, and PingGateway will reload changed routes every 10 seconds by default.

The PingGateway capture decorator is particularly useful when troubleshooting routes. To use it quickly, add "capture": "all" to an object in a route, and let PingGateway reload the route before you try it. It logs messages in the server output about incoming requests at any point until PingGateway sends the request, and outgoing responses at any point until PingGateway delivers the response.

For more information, see the PingGateway product documentation.

Adapt the PingAM configuration

A sample deployment configured according to Separate identity stores or Shared identity store does not route the traffic through PingGateway. Adapt the PingAM and OAuth 2.0 client configurations to use PingGateway.

The following minimal changes are sufficient to use the sample deployment. Add any additional changes necessary for your deployment:

If you’re not currently logged in to the AM admin UI as the amAdmin user, log in.

The password used in the documentation to set up the platform is Passw0rd.
In the Top Level Realm and the alpha realm, add redirect URIs for the end-user-ui OAuth 2.0 client:

https://platform.example.com:9443/enduser-ui/appAuthHelperRedirect.html
https://platform.example.com:9443/enduser-ui/sessionCheck.html
In the Top Level Realm and the alpha realm, add redirect URIs for the idm-admin-ui OAuth 2.0 client:

https://platform.example.com:9443/platform/appAuthHelperRedirect.html
https://platform.example.com:9443/platform/sessionCheck.html
https://platform.example.com:9443/admin/appAuthHelperRedirect.html
https://platform.example.com:9443/admin/sessionCheck.html
https://platform.example.com:9443/platform-ui/appAuthHelperRedirect.html
https://platform.example.com:9443/platform-ui/sessionCheck.html
In the alpha realm, edit Success URLs for the following PingAM trees:

PlatformLogin

Success URL: https://platform.example.com:9443/enduser-ui/?realm=/alpha

PlatformRegistration

Success URL: https://platform.example.com:9443/enduser-ui/?realm=/alpha

PlatformResetPassword

Success URL: https://platform.example.com:9443/enduser-ui/?realm=/alpha
Update these settings:
Top Level Realm > Authentication > Settings > General

External Login Page URL: https://platform.example.com:9443/platform-login

Top Level Realm > Services
+ Add a Service > Validation Service.

In Valid goto URL Resources, set:

https://platform.example.com:9443/*
https://platform.example.com:9443/*?*
Top Level Realm > Services
+ Add a Service > Base URL Source.

In Base URL Source, choose Fixed value.

In Fixed value base URL, set https://platform.example.com:9443.
alpha Realm > Authentication > Settings > General

External Login Page URL: https://platform.example.com:9443/enduser-login

alpha Realm > Services > Validation Service

To Valid goto URL Resources, add:

https://platform.example.com:9443/*
https://platform.example.com:9443/*?*

alpha Realm > Services
+ Add a Service > Base URL Source.

In Base URL Source, choose Fixed value.

In Fixed value base URL, set https://platform.example.com:9443.
Configure > Global Services > CORS Service > Secondary Configurations > Cors Configuration

To Accepted Origins, add: https://platform.example.com:9443.

Adapt the PingIDM configuration

In the /path/to/openidm/conf/ui-configuration.json file, change configuration > platformSettings > amUrl to access the PingIDM UI through PingGateway:

{
    "configuration" : {
        "platformSettings" : {
            "adminOauthClient" : "idm-admin-ui",
            "adminOauthClientScopes" : "fr:idm:*",
            "amUrl" : "https://platform.example.com:9443/am",
            "loginUrl" : ""
        }
    }
}

Once you make this change, you can no longer access the IDM admin UI directly over HTTP. Use the link in the Platform Admin UI to access the IDM admin UI.

Ping Identity Platform