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 installations, 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.
- 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.
For information about important fixes made over several releases, see Critical Fixes.
Considerations when upgrading to 8.3.0.0
Keep in mind the following important considerations for upgrading to this version of PingAuthorize Server.
- General
-
- If you are upgrading to PingAuthorize 8.3.0.0, you must also upgrade to PingAuthorize Policy Editor 8.3.0.0.
- The policy decision service configuration has changed. When using embedded pdp mode, you
must specify a
deployment-package-source-type
for the policy decision service in your configuration. You might need to update the dsconfig files in your server profile when upgrading to version 8.3 to set adeployment-package-source-type
. If you want to maintain the existing behavior from previous releases, use"static-file"
as yourdeployment-package-source-type
.
- Deployments with multi-server topologies
-
-
Upgrading from PingDataGovernance 6.x or 7.x
Upgrading multi-server topologies that contain PingDataGovernance 6.x or 7.x is not supported.
-
Upgrading from PingDataGovernance 8.0.0.0 or later
You can upgrade multi-server topology deployments that contain PingDataGovernance 8.0.0.0 or later to PingAuthorize. When updating a PingDataGovernance multi-server topology to PingAuthorize, you must remove all servers from the topology, update each server individually, then add all the servers back to the topology, as explained below.
Note:The known issues and workarounds in this section apply only to deployments with multi-server PingDataGovernance topologies. Deployments with single-server topologies can upgrade without these issues.
For each server to be upgraded:
-
Remove the server from the topology by running a command like this one.
manage-topology remove-server <connection args>
-
Update the server.
After you have successfully upgraded every server, you can then join each server to the topology by running a command like this one.
manage-topology add-server <connection args> <remote server connection args>
If you do not follow these steps, adding a PingAuthorize server to a PingDataGovernance topology could result in the following error message:
Entry cn=License,cn=Topology,cn=config cannot be modified because one of the configuration change listeners registered for that entry rejected the change: The provided license key was generated for PingAuthorize but this is PingDataGovernance with Symphonic
Another consequence of not following these steps is that restarting any server in the topology that is not updated fails. To use the server again, you must remove the server from the topology and reset its license to a PingDataGovernance license.
-
-
- Upgrading from a version earlier than 7.3.0.0
- If you are upgrading from a PingDataGovernance version earlier than 7.3.0.0, PingAuthorize creates the deleted-oauth2-scopes.txt file to capture data that can simplify the upgrade. For information about what to do with this file, contact your Ping Identity account representative.
Considerations when upgrading to 8.2.0.0
Keep in mind the following important considerations for upgrading to this version of PingDataGovernance Server.
- General
-
- If you are upgrading to PingDataGovernance 8.2.0.0, you must also upgrade to Policy Administration GUI 8.2.0.0.
-
Changes to SpEL expressions using collection projection might cause policy errors with the following form.
EL1004E: Method call: Method <Symphonic Value method>() cannot be found on type <native Java type>
If your policies rely on SpEL collection projection and methods like intValue(), stringValue(), jsonRepresentation(), or pojoRepresentation(), you must update these expressions. It is recommended that you update the policies to use collection transforms instead of SpEL collection projection. For information about collection transforms, see the PingDataGovernance Policy Administration Guide.
- This upgrade moves to Jetty 9.4. As a result, the HTTPS connection
handler will no longer support TLS_RSA ciphers by default. If you
use any legacy HTTPS clients that still require TLS_RSA ciphers,
modify the
ssl-cipher-suite
property of the HTTPS Connection Handler to include them.
- Gateway API Endpoint and Sideband API Endpoint configurations
-
-
PingDataGovernance now strictly validates path parameters used in Gateway API Endpoint and Sideband API Endpoint configurations. The
inbound-base-path
value (for Gateway API Endpoints) and thebase-path
value (for Sideband API Endpoints) no longer allow duplicate path parameters. For example, "/Users/{userId}/Manager/{userId}" defines the "userId" path parameter twice and is invalid. In addition, other configuration properties cannot refer to a path parameter that is not defined byinbound-base-path
orbase-path
.Previously, the server would allow such invalid configuration changes to be saved, but now the server rejects them. Upgrades or server profile deployments including invalid configuration of this kind will now fail. If this happens, correct the invalid configuration values.
-
Considerations when upgrading to 8.1.0.0
- General
-
-
PingDataGovernance 8.1.0.0 uses a new policy request format that requires changes to the Trust Framework.
If you are using policies intended for a previous release, you can continue to use your existing policies by setting the
trust-framework-version
property of the Policy Decision Service to v1. If you upgrade your server using the update tool, this property is set for you automatically.The v1 format is deprecated, however, and you are strongly encouraged to update your Trust Framework as soon as possible. To do this, load your existing policies in the Policy Administration GUI and apply the Trust Framework changes by going to resource/policies/upgrade-snapshots/8.0.0.0-to-8.1.0.0.SNAPSHOT file included with the server. Then, configure PingDataGovernance Server to issue policy requests using the new Trust Framework by setting the
and selecting thetrust-framework-version
property of the Policy Decision Service to v2. - If you are upgrading to PingDataGovernance 8.1.0.0, an updated version of the Policy Administration GUI is required.
- The PingDataGovernance Policy Administration GUI no longer uses the UNIX environment variable PING_HOSTNAME. Instead, server administrators should use PING_EXTERNAL_BASE_URL to specify both the domain and the port. For more information, see the PingDataGovernance Server Administration Guide.
-
- Policy processing and advice
-
- The Allow Attributes advice and the Prohibit Attributes advice have been removed and can no longer be used. Requests involving policies that refer to these advice types will fail.
- The
HttpRequest.Headers
policy request attribute is not available starting with Trust Framework version v2. It has been replaced by theHttpRequest.RequestHeaders
andHttpRequest.ResponseHeaders
policy request attributes. Update existing policies or Trust Framework entities that refer toHttpRequest.Headers
to refer toHttpRequest.RequestHeaders
. - SCIM 2 requests now include the resource type in the service value during policy processing. For example, for a SCIM 2 request that affects the "Users" resource type, the service value will now be "SCIM2.Users" instead of "SCIM2". Existing policy rules or targets that rely on an exact equality match for "SCIM2" must be updated. For example, a condition of "Service Equals SCIM2" would need to be updated to "Service Matches SCIM2".
- For security, by default, the policy engine's SpEL processor now
invokes Java classes only in the
allow-list
presented in the PingDataGovernance Server Administration Guide. To use other classes, add a key to thecore
section of the Policy Administration GUI's configuration calledAttributeProcessing.SpEL.AllowedClasses
with a list of the classes to include. If you are using embedded PDP mode, add a policy configuration key of the same name to the PingDataGovernance Server configuration.
- PDP API
-
- The XACML-JSON PDP API now requires a different request format. With this new format, you can make multiple decisions using a single HTTP request. In addition, the response format is now compliant with the XACML-JSON specification. The 8.0 PDP API request format is no longer supported. For more information, see the PingDataGovernance Server Administration Guide.
- Peer setup and clustered configuration
-
- Peer setup and clustered configuration are deprecated and will be removed in PingAuthorize 9.0. We encourage deployers to manage server configuration using server profiles, which support deployment best practices such as automation and Infrastructure-as-Code (IaC). For more information about server profiles, see the PingAuthorize Server Administration Guide.
- If you have upgraded a server that is in a cluster (that is, has a cluster name set in the Server Instance configuration object) to version 8.1, you will not be able to make cluster configuration changes until all servers with the same cluster name have been upgraded to version 8.1. If needed, you could create temporary clusters based on server versions and modify each server's cluster name appropriately to minimize the impact while you are upgrading.