PingAccess

Upgrade considerations

Specific changes in PingAccess might require additional steps during an upgrade to the latest version.

Java 8

With continued product and hardware security module (HSM) integration improvements, customers should migrate off of Java 8. Ping Identity removed Java 8 support from the qualification process in December 2023. For more information, including Java 11 support, see Installation requirements.

Performing a zero downtime upgrade from 6.0, 6.0.1, 6.0.2, or 6.0.3 to a later version

If you’re using PingAccess 6.0, 6.0.1, 6.0.2, or 6.0.3, zero-downtime upgrades to later versions might fail because of PKCE changes.

To prevent this issue, edit your existing web sessions and enable PKCE support:

  1. Click Access and then go to Web Sessions → Web Sessions.

  2. Expand the web session and click the pencil icon ().

  3. Click Show Advanced.

  4. Click Enable PKCE.

  5. Edit the web session. Click Save.

  6. Repeat these steps for each web session.

New templates for error and logout pages

PingAccess 6.1 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

For more information about the templates, see User-facing page customization reference. If you have previously customized the template files, you can re-customize them using the new files.

Using a proxied PingFederate deployment

The PingAccess 6.2 Beta introduced the ability to configure a proxied PingFederate deployment through PingAccess. If you have manually configured a similar deployment in an earlier version of PingAccess, 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 to verify that it can manage the use cases of your current configuration. Remove any PingFederate-related applications before migrating the configuration.

SPA support

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

The SPA support check box is still available for application programming interface (API) type applications and Web + API type applications. For more information, see Application field descriptions.

If the default settings for SPA support with Web type applications aren’t compatible with your environment or with a specific application, change the default authentication policy or create an authentication challenge policy to replace these settings and achieve the desired behavior. For more information, see Changing the default authentication challenge policy and Configuring authentication challenge policies.

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. For more information, see PingAccess 7.1 (June 2022) and Authentication.

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. For more information, see 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

The PingAccess 7.3 Beta introduces a new log4j-categories.xml file to enable adjustment of the amount of detail included in PingAccess’s logs. For more information, see 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 that you upgrade to PingAccess 7.3 or a later version.

Elliptic Curve key pair issues with AWS CloudHSM Client SDK 5

As of the PingAccess 7.3 Beta, 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. For more information on clustering and configuration data replication, see 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.

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.