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, refer to Planning your upgrade.

Considerations when upgrading to 10.3 or later

Custom SDK extensions using Javax must be migrated and recompiled

Several components were upgraded in version 10.3 of PingAuthorize. If any of your custom Server SDK extensions have classes that import javax.* packages, you must migrate them to the equivalent jakarta.* packages and then recompile the extensions.

Camel upgrade

PingAuthorize 10.3 now supports Apache Camel 4.0. The limitations on using Apache Camel to connect policy information points (PIP) introduced in PingAuthorize 9.3 still apply. You can find more information on working around these limitations in Enabling Camel service connections. Learn how to upgrade PingAuthorize versions 10.0-10.2 using Camel 3.x in the Apache Camel 3.x to 4.0 migration guide.

Java considerations

Support for Java 11 has been removed, and upgrading to Version 10.3 of PingAuthorize will fail unless you are running Java 17 or 21.

Prerequisites for upgrading

You must meet one of the following requirements:

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

If you use environment variables to point to your Java installation, these will override your default Java version. We recommend you set only one variable. If both are set, UNBOUNDID_JAVA_HOME takes precedence.

Java 11 is no longer supported. You can’t upgrade a server instance to version 10.3 without first updating Java to a supported version.

Upgrading from a server running a supported version of Java

If you’re upgrading a server running Java 17 or 21 to version 10.3, you can proceed with the server upgrade.

Upgrading from a server running an unsupported version of Java

Before upgrading the server to version 10.3, you must install either Java 17 or 21. Learn more in System requirements. Upgrading to version 10.3 after updating Java requires changes to the java.properties file.

You must also meet one of the prerequisites listed in the previous section before upgrading the server.

Select one of the following options for modifying the java.properties file. Where a Java version is specified, substitute your installed, supported Java version.

Option 1: Before upgrading the server, convert the file manually:
1. Edit the config/java.properties file to update the Java version and convert the JVM parameters to be specific to Java 17.
2. Run the bin/dsjavaproperties command to put the changes into effect.
Option 2: 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 17 java.properties file.
  
  For this option, run:
  bin/dsjavaproperties --initialize
3. Upgrade the server using the generated java.properties file, and then restore your customized settings from the original file.
Option 3: Allow the upgrade to replace the file:
1. Upgrade the server to version 10.3.
  
  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 Policy Editor instance running an unsupported version of Java

If you are upgrading from a Policy Editor instance running an unsupported version of Java, 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.3, including bin/setup and bin/start-server.

Considerations when upgrading to 10.1 or later

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.

Considerations when upgrading to 10.0 or later

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.