--- title: Upgrade considerations description: When upgrading, you must consider factors such as the scope of the update, the PingAuthorize or PingDataGovernance version from which you're upgrading, and if you're not using Docker, your installed version of Java. component: pingauthorize version: 11.0 page_id: pingauthorize:upgrading_pingauthorize:paz_upgrade_consids canonical_url: https://docs.pingidentity.com/pingauthorize/11.0/upgrading_pingauthorize/paz_upgrade_consids.html revdate: December 15, 2025 section_ids: general-considerations: General considerations considerations-when-upgrading-to-11-0-or-later: Considerations when upgrading to 11.0 or later url-decoding-behavior-standardization: URL decoding behavior standardization aws-java-sdk-upgrade: AWS Java SDK upgrade considerations-when-upgrading-to-10-3-or-later: Considerations when upgrading to 10.3 or later custom-sdk-extensions-using-java-ee-javax-packages-must-be-migrated-and-recompiled: Custom SDK extensions using Java EE javax packages must be migrated and recompiled camel-upgrade: Camel upgrade java-considerations: Java considerations prerequisites-for-upgrading: Prerequisites for upgrading upgrading-from-a-server-running-a-supported-version-of-java: Upgrading from a server running a supported version of Java upgrading-from-a-server-running-an-unsupported-version-of-java: Upgrading from a server running an unsupported version of Java upgrading-a-policy-editor-instance-running-an-unsupported-version-of-java: Upgrading a Policy Editor instance running an unsupported version of Java considerations-when-upgrading-to-10-1-or-later: Considerations when upgrading to 10.1 or later resolving-issues-with-copying-policy-elements: Resolving issues with copying policy elements upgrade_consids_100: Considerations when upgrading to 10.0 or later sni-hostname-checking-disabled-by-default: SNI hostname checking disabled by default --- # Upgrade considerations When upgrading, you must consider factors such as the scope of the update, the PingAuthorize or PingDataGovernance version from which you're upgrading, and if you're 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: * 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 [Best Practices: Planning your upgrade](https://docs.pingidentity.com/solution-guides/best_practice_guides/htg_plan_software_upgrade.html). | ## Considerations when upgrading to 11.0 or later ### URL decoding behavior standardization * Changes We've standardized URL decoding behavior to address a security vulnerability that permitted double-URL-encoded requests to bypass path-based access controls. * **Policy evaluation**: The PingAuthorize Server now decodes the incoming request URL, including the path and query parameters, exactly once before policy evaluation. * **Request forwarding**: The PingAuthorize Server now forwards the original, unmodified request URL to the backend resource server. * Required action Backend resource servers must now perform their own URL decoding in accordance with [RFC-3986](https://datatracker.ietf.org/doc/html/rfc3986). If your resource servers previously relied on PingAuthorize to forward fully-decoded request URLs, now these servers might fail to process encoded URLs correctly. Update these servers to handle encoded URLs or deploy a proxy to decode traffic before it reaches the server. ### AWS Java SDK upgrade * Changes We've upgraded to AWS Java SDK v2. This upgrade changes the default behavior for Amazon S3 connections to use virtual-hosted-style URLs, disabling legacy path-style access by default. * Required action If your Amazon S3 deployment package stores require path-style access (for example, `https://s3.amazonaws.com/`), enable the **Use Path Style Access** option in the PingAuthorize S3 store configuration to maintain connectivity. Learn more in [Adding an Amazon S3 deployment package store to PingAuthorize](../pingauthorize_server_administration_guide/paz_amazons3_deploy_package.html). ## Considerations when upgrading to 10.3 or later ### Custom SDK extensions using Java EE `javax` packages must be migrated and recompiled Several components were upgraded in version 10.3 of PingAuthorize. If any of your custom Server SDK extensions import `javax.*` packages that are part of the Java EE specification (such as `javax.servlet` or `javax.ws.rs`), you must migrate them to the equivalent `jakarta.*` packages and recompile the extension. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------- | | | `javax.*` packages that are part of standard Java SE (such as `javax.crypto` or `javax.sql`) are unaffected and don't require migration. | ### 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](../pingauthorize_policy_administration_guide/paz_camel_enable.html). 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](https://camel.apache.org/manual/camel-4-migration-guide.html). ### 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](paz_upgrade_pingauthorize.html). ##### 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](../installing_and_uninstalling_pingauthorize/paz_system_requirements.html). 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](../pingauthorize_policy_administration_guide/paz_entity_copy_troubleshooting.html). ## Considerations when upgrading to 10.0 or later ### SNI hostname checking disabled by default If you're upgrading to PingAuthorize 10.0 or later 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.