PingAccess

Upgrade considerations

The following changes between PingAccess versions might require additional steps during an upgrade.

Considerations when upgrading to 6.0 or later

New templates for error and logout pages

In PingAccess 6.1, we updated several error and logout page template files to modernize their appearance and remove Ping branding:

  • general.loggedout.page.template.html

  • general.error.page.template.html

  • admin.error.page.template.html

  • policy.error.page.template.html

You can find more information about the templates in User-facing page customization reference. If you customized the template files previously, recustomize the new files.

Using a proxied PingFederate deployment

PingAccess 6.2 introduced the ability to configure a proxied PingFederate deployment through PingAccess. If you configured a similar deployment in an earlier version of PingAccess manually, you can continue to use it.

However, if you plan to switch from a deployment that you configured manually to a proxied PingFederate deployment through PingAccess:

  • Review the configuration options in the proxied PingFederate deployment admin console. Verify that it can support your current configuration’s use cases.

  • Remove any PingFederate-related applications before migrating the configuration.

SPA support

We removed the single-page application (SPA) support checkbox from the admin UI for Web applications in PingAccess 6.2. Consequently, all Web applications created in PingAccess 6.2 and later have SPA support enabled by default.

The SPA support checkbox is still available for API applications and Web + API applications. You can find more information in Application field descriptions.

If the default settings for SPA support with Web applications aren’t compatible with your environment or with a specific application, you can change the default authentication policy or create a new authentication challenge policy.

PingAccess 7.1 added a system-provided authentication challenge policy that disables SPA support by default. This policy is useful if you aren’t onboarding any new SPAs and don’t have many SPAs in your current environment. Learn more in Authentication.

Considerations when upgrading to 7.0 or later

Runtime state clustering removal

Support for runtime state clustering was removed in PingAccess 7.0. However, one benefit of runtime state clustering was that it enabled rate limiting rules to behave more consistently in a clustered environment. This was because runtime state clustering enabled all of the engines in a cluster to know the total number of requests for a resource, not just the requests which that engine received.

If you’re using runtime state clustering with rate limiting rules, before upgrading to PingAccess 7.0 or later, you should either:

  • Configure a load balancer sitting in front of a PingAccess cluster to stick the session to a specific engine. This ensures that a single PingAccess engine node applies the rate limiting rule. Learn more in Managing load balancing strategies.

  • Tune down the Max Burst Requests interval on the rate limiting rule, following the <current max burst requests interval>/<number of engines in cluster> ratio.

Upgrading to or past version 7.3 with a customized log4j2.xml file

PingAccess 7.3 introduced a new log4j-categories.xml file to enable adjustment of the amount of detail included in PingAccess’s logs. Learn more in Configuring verbose logging in the admin console.

If you have customized your log4j2.xml file, you must merge this file with the log4j-categories.xml file the first time you upgrade to PingAccess 7.3 or a later version.

Elliptic Curve key pair issues with AWS CloudHSM Client SDK 5

As of PingAccess 7.3, PingAccess offers support for Amazon Web Services (AWS) CloudHSM Client SDK 5 instead of Client SDK 3.

Client SDK 5 introduces an issue with elliptic curve (EC) key pairs for all TLS handshakes, similar to the extant issue with TLS 1.3 for EC and RSA keys. As a result, you can create EC key pairs in PingAccess, but you can’t assign them to a listener.

Improved configuration replication compatibility

PingAccess 7.3 introduced the ability for engine nodes and the replica administrative node to connect to an administrative node that’s running a later version of PingAccess. This ability was backported to PingAccess 7.2.2 as well.

Nodes running PingAccess 7.2.2 or later can replicate data that’s relevant for the version of PingAccess that they’re running from the administrative node. You can find more information on clustering and configuration data replication in Clustering in PingAccess.

This ability to maintain compatibility reduces the possibility for outages caused by outdated information, providing more flexibility during the upgrade process for those with large scale or hybrid environments. It also improves stability for containerized deployments because clustered engine nodes don’t need to maintain their replication data throughout a restart.

You should still finish upgrading the engine nodes as soon as possible and avoid making configuration changes until all engines have been upgraded.

Considerations when upgrading to 8.0 or later

Upgrading to or past version 8.0 from version 6.2 or below

If you have PingAccess 6.2 or below, you cannot upgrade directly to PingAccess 8.0. You must upgrade to a version above 6.2 first, and then upgrade to 8.0.

This is because in PingAccess 8.0, an outdated H2 JAR file was removed, and PingAccess 6.2 and below use an H2 embedded database.

pa.keystore.pw encryption enforcement

PingAccess 8.3 and later enforce encryption of the pa.keystore.pw property in the run.properties file as follows:

  • In non-FIPS mode, if you don’t obfuscate pa.keystore.pw, PingAccess logs a warning during startup.

  • If you try to enable FIPS mode without obfuscating pa.keystore.pw, PingAccess terminates startup and logs an error message.

Considerations when upgrading to 9.0 or later

Java 11 removal

Ping Identity removed Java 11 support from PingAccess in December 2025. You must upgrade to a supported Java version before installing PingAccess 9.0 or later. Learn more about supported java versions in PingAccess system requirements.

RSA 1.5 with PKCS#1 removal

Ping Identity removed support for RSA 1.5 with PKCS#1 in PingAccess 9.0.

Automatically rotate the admin config query certificate

PingAccess 9.1 now uses a two-port certificate rotation approach for the admin config query listener. Engine nodes poll the /engines/rest/config-query-certificate endpoint to retrieve new certificates and add them to the engine node’s truststore.

After upgrading to PingAccess 9.1 or later:

  • Consider whether you need to change the rotation window or the temporary rotation port. Learn more in the PingAccess configuration file reference and Port requirements.

  • If using Linux, make sure any clustered PingAccess engine nodes have the write permission so they can modify the bootstrap.properties file. If these nodes don’t have the correct file permissions, making updates to the config query listener can cause unexpected behavior.