Upgrade considerations

When upgrading, you must consider factors such as the scope of the update, the PingAuthorize or PingDataGovernance version from which you are upgrading, and if you are not using Docker, your installed version of Java.

The 8.3.0.0 release is the first release of PingAuthorize. Previously, the product was known as PingDataGovernance.

General considerations

For Docker deployments, the upgrade process involves downloading and deploying the latest containers.

For manual installations, the upgrade process involves downloading and extracting a new version of the PingAuthorize Server .zip file on the server and running the update utility with the --serverRoot or -R option value from the new root server pointing to the installation.

Consider the following when upgrading:

If you are upgrading from a PingAuthorize Early Access release to a PingAuthorize General Availability release, you must upgrade both the PingAuthorize Server and the Policy Editor before you use the Policy Decision Service in external mode. Upgrading only one component results in this error: Please upgrade to PingAuthorize Policy Editor version <X.X.X.X>.
The update affects only the server being upgraded. The process does not alter the configuration of other servers, so you must update those servers separately.
The update tool verifies that the installed version of Java meets the new server requirements. To simplify the process, install the version of Java that is supported by the new server before running the tool.
Upgrades for PingDataGovernance Server are only supported from versions 7.0.0.0 or later. If upgrading from a version of PingDataGovernance prior to 7.3.0.0, configuration loss will occur. The update tool has a warning message about this.

For additional considerations, see Planning your upgrade.

Upgrade considerations introduced in PingAuthorize 10.1

Resolving issues with copying policy elements

After upgrading from a version of PingAuthorize earlier than 10.1 and attempting to delete a copy of a Policy Editor element, that copy might persist in the UI and return an error when selected. To completely remove deleted copies from the Policy Editor, follow the steps in Deleting persistent copies.

Upgrade considerations introduced in PingAuthorize 10.0

Camel upgrade

PingAuthorize 10.0 now supports Apache Camel 3.21.2. The limitations on using Apache Camel to connect policy information points (PIP) introduced in PingAuthorize 9.3 still apply. For more information on working around these limitations, see Enabling Camel service connections. For details on upgrading from Apache Camel 2.x to 3.0, see Apache’s migration guide.

SNI hostname checking disabled by default

If you are upgrading to PingAuthorize 10.0 with an existing configuration that has SNI hostname checks enabled, you might encounter an issue when using a host name not found in the key store. To migrate an existing configuration from an earlier version of PingAuthorize and disable SNI host name checks, add the following to your configuration.yml file:

server:
  ...
  applicationConnectors:
  - type: "https"
    ...
    disableSniHostCheck: "${PING_DISABLE_SNI_HOSTNAME_CHECKS:-true}"

This change also introduces a new setup option, --disableSniHostnameChecks, that you can set to false to enable SNI hostname checks.

Upgrading a PingAuthorize server running Java 8 to version 10.0

Support for Java 8 has been deprecated, and upgrading to Version 10.0 of PingAuthorize will fail unless you are running Java 11 or 17.

If you are upgrading a server running Java 11 or 17 to version 10.0, you can proceed with the server upgrade after confirming one of the following:

Your default Java installation is a supported version.
You are pointing one of the following environment variables to a supported version of Java:
- JAVA_HOME
- UNBOUNDID_JAVA_HOME

The java.properties configuration file won’t be modified if you upgrade the server to version 10.0 under the previous conditions.

The upgrade process from a server instance running Java 8 is not automatic and will fail. Java 8 is no longer supported.

Updating to a supported Java version before upgrading the server

Before upgrading the server to version 10.0, you must install either Java 11 or 17. For more information, see System requirements. Upgrading to version 10.0 after updating Java requires changes to the java.properties file.

Select one of the following options for handling how java.properties gets modified. Where a Java version is specified, substitute your installed, supported Java version.

Before updating the server, convert the file manually:
1. Edit config/java.properties file to convert the JVM parameters to be specific to Java 11.
2. Run bin/jds/javaproperties to make the changes go into effect.
Before upgrading the server, create a new file:
1. Rename the old java.properties file.
2. Run the bin/dsjavaproperties command to initialize a new Java 11 java.properties file.
  
  For this option, run the following command:
  bin/dsjavaproperties --initialize
3. Use the generated file as a reference for converting the original java.properties file. Alternatively, upgrade the server using the generated file, and then restore your customized settings afterward.
Allow the upgrade to replace the file:
1. Upgrade the server to version 10.0.
  
  The upgrade process will overwrite the java.properties file and the original file will be saved as java.properties.old. A java.properties.change file will also be created, containing the diff output between the new and old java.properties files.
2. Restore or convert the JVM settings that were overwritten during the upgrade process.

Upgrading a PingAuthorize Policy Editor running Java 8 to version 10.0

If you are upgrading from a PingAuthorize Policy Editor instance running Java 8, you must export the JAVA_HOME environment variable by running the following command:

export JAVA_HOME=$JAVA11_HOME

You must perform this export before running any scripts in PingAuthorize 10.0, including bin/setup and bin/start-server.