--- title: Protect the deployment description: This is not a comprehensive Advanced Identity Software implementation guide. These sample setup instructions show a minimal integration of Advanced Identity Software components to get you started. component: platform version: 8 page_id: platform:sample-setup:protect-deployment canonical_url: https://docs.pingidentity.com/platform/8/sample-setup/protect-deployment.html page_aliases: ["platform-setup-guide:protect-deployment.adoc"] section_ids: before_you_start: Before you start protect-prepare-keys: Prepare keys protect-install-ig: Install PingGateway protect-trust-ca: Trust the deployment ID certificate protect-configure-ig: Configure PingGateway protect-am-config: Adapt the PingAM configuration protect-idm-config: Adapt the PingIDM configuration next_step: Next step --- # Protect the deployment | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This is *not* a comprehensive Advanced Identity Software implementation guide. These sample setup instructions show a minimal integration of Advanced Identity Software components to get you started.Ping Advanced Identity Software offers maximum extensibility and flexibility in self-managed deployments. Advanced Identity Software 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 Advanced Identity Software as a service, use [PingOne Advanced Identity Cloud](https://docs.pingidentity.com/pingoneaic). - To deploy in Kubernetes, start with the [ForgeOps](https://docs.pingidentity.com/forgeops/2025.1) reference implementation.For help with your deployment and to validate your plans before deploying in production, contact [Ping Identity](https://www.pingidentity.com). | ## Before you start After you set up a sample deployment according to [Separate identity stores](deployment1.html) or [Shared identity store](deployment2.html), you have a functionally complete Ping Advanced Identity Software 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 Advanced Identity Software, 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: ```none 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](https://docs.pingidentity.com/pinggateway/2025.11). ## 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.1) You'll generate an PingGateway server key pair using the PingDS `dskeymgr` command. 2) 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: 1. Save a password file for the keystore: ```bash 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. 2. Set the deployment ID in an environment variable that you'll use in `dskeymgr` commands: ```bash export DEPLOYMENT_ID=deployment-id ``` 3. Generate a server key pair for PingGateway to use for HTTPS: ```bash /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 ``` 4. Inspect the contents of the keystore you just created to find the key alias is `ssl-key-pair`: ```bash 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, , PrivateKeyEntry, Certificate fingerprint (SHA-256): ``` 5. Copy the keystore and password to the system where PingGateway runs. 6. Export the deployment ID CA certificate to trust: ```bash /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 Advanced Identity Software 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. 1. Download PingGateway-2025.11.1.zip. 2. Unpack the files. This example shows the files unpacked in the `/path/to/identity-gateway-2025.11.1` directory. 3. Create a configuration directory for PingGateway: ```bash mkdir -p $HOME/.openig/config/ ``` The default PingGateway configuration directory is `$HOME/.openig/config` on Linux and UNIX, and `%appdata%\OpenIG\config` on Windows. 4. Add an [admin.json](../_attachments/ig/config/admin.json) configuration file for HTTPS support at the root of the PingGateway configuration directory. > **Collapse: Sample admin.json** > > This example expects the keystore and `keystore.pin` file in the `/path/to/security/` directory: > > ```json > { > "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" > } > ] > } > ``` 5. Start PingGateway: ```bash /path/to/identity-gateway-2025.11.1/bin/start.sh ... [main] INFO ... started in XXXXms on ports : [9080, 9443] ``` 6. Test that you can use the PingGateway "ping" endpoint over HTTP: ```bash 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. 7. When you can successfully ping PingGateway over HTTP, try HTTPS using your CA certificate file: ```bash 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](platform-ui.html): 1. Add a [config.json](../_attachments/ig/config/config.json) configuration file at the root of the PingGateway configuration directory. > **Collapse: Sample config.json** > > This example configures the capture decorator and a router with a default route: > > ```json > { > "heap": [ > { > "name": "capture", > "type": "CaptureDecorator" > }, > { > "name": "DefaultRoute", > "type": "StaticResponseHandler", > "config": { > "status": 200, > "headers": { > "Content-Type": [ > "text/html" > ] > }, > "entity": "

End user access

Admin access

" > } > }, > { > "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 Advanced Identity Software before logging in, or after logging out. In this example, the page includes a link for each of the two user flows: 1. An end user logs in to access their applications and profile page through the End User UI. 2. An admin logs in to configure Advanced Identity Software 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. 2. Create a `routes` directory under the PingGateway configuration file directory: ```bash mkdir $HOME/.openig/config/routes ``` 3. Add a [login.json](../_attachments/ig/config/routes/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: > **Collapse: Sample login.json for Login UI from a Docker image** > > ```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" > } > } > } > ``` > **Collapse: Sample for End User UI from a .zip file** > > ```json > { > "name": "login", > "condition": "${find(request.uri.path, '^/enduser-login|^/platform-login')}", > "baseURI": "http://am.example.com:8081", > "handler": { > "type": "Chain", > "config": { > "filters": [ > { > "type": "UriPathRewriteFilter", > "config": { > "mappings": { > "/enduser-login": "/am/XUI", > "/platform-login": "/am/XUI" > }, > "failureHandler": "DefaultRoute" > } > } > ], > "handler": "ReverseProxyHandler" > } > } > } > ``` 4. Add an `enduser-ui.json` route file in the `routes` directory. This route sends end users to the End User UI: > **Collapse: Sample for End User UI from a Docker image** > > ```json > { > "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" > } > } > } > ``` > **Collapse: Sample for End User UI from a .zip file** > > ```json > { > "name": "enduser-ui", > "condition": "${find(request.uri.path, '^/enduser-ui')}", > "baseURI": "http://enduser.example.com:8081", > "handler": { > "type": "Chain", > "config": { > "filters": [ > { > "type": "UriPathRewriteFilter", > "config": { > "mappings": { > "/enduser-ui": "/enduser" > }, > "failureHandler": "DefaultRoute" > } > } > ], > "handler": "ReverseProxyHandler" > } > } > } > ``` 5. Add a `platform-ui.json` route file in the `routes` directory. This route sends administrators to the Admin UI: > **Collapse: Sample for Admin UI from Docker images** > > ```json > { > "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" > } > } > } > ``` > **Collapse: Sample for Admin UI from a .zip file** > > ```json > { > "name": "platform-ui", > "condition": "${find(request.uri.path, '^/platform-ui')}", > "baseURI": "http://admin.example.com:8081", > "handler": { > "type": "Chain", > "config": { > "filters": [ > { > "type": "UriPathRewriteFilter", > "config": { > "mappings": { > "/platform-ui": "/platform" > }, > "failureHandler": "DefaultRoute" > } > } > ], > "handler": "ReverseProxyHandler" > } > } > } > ``` 6. Add an [am.json](../_attachments/ig/config/routes/am.json) route file in the `routes` directory. This route handles requests to PingAM, ensuring that the browser gets redirected through PingGateway: > **Collapse: Sample am.json** > > ```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" > } > } > } > ``` 7. Add an [idm.json](../_attachments/ig/config/routes/idm.json) route file in the `routes` directory. This route handles requests to PingIDM, ensuring that the browser gets redirected through PingGateway: > **Collapse: Sample idm.json** > > ```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" > } > } > } > ``` 8. 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](https://docs.pingidentity.com/pinggateway/2025.11). ## Adapt the PingAM configuration A sample deployment configured according to [Separate identity stores](deployment1.html) or [Shared identity store](deployment2.html) 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: 1. 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 Advanced Identity Software is `Passw0rd`. 2. 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` 3. 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` 4. 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` 5. 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: ```json { "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. ## Next step * [icon: check-square-o, set=fa][Choose your sample](overview.html) * [icon: check-square-o, set=fa][Prepare the servers](server-settings.html) * Separate identity stores * [icon: check-square-o, set=fa][Set up PingDS](deployment2.html) * [icon: check-square-o, set=fa][Set up PingAM](am-setup-1.html) * [icon: check-square-o, set=fa][Set up PingIDM](idm-setup-1.html) * Shared identity store * [icon: check-square-o, set=fa][Set up PingDS](deployment2.html) * [icon: check-square-o, set=fa][Set up PingAM](am-setup-2.html) * [icon: check-square-o, set=fa][Set up PingIDM](idm-setup-2.html) * [icon: check-square-o, set=fa][Protect the deployment](protect-deployment.html) * [icon: square-o, set=fa]*[Set up the Platform UIs](platform-ui.html)* * [icon: square-o, set=fa][Test your deployment](test-deployment.html)