Upgrade considerations introduced in PingAuthorize 8.x

Considerations introduced in PingAuthorize 8.3.0.0

Keep in mind the following important considerations introduced in 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 policy decision point (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 a deployment-package-source-type. If you want to maintain the existing behavior from previous releases, use "static-file" as your deployment-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.

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 introduced in PingDataGovernance 8.2.0.0

Keep in mind the following important considerations introduced in 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 application programming interface (API) endpoint and sideband API endpoint configurations. The inbound-base-path value (for gateway API endpoints) and the base-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 by inbound-base-path or base-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 introduced in PingDataGovernance 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 Branch Manager → Merge Snapshot and selecting the 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 trust-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 attributes is not available starting with Trust Framework version v2. It has been replaced by the HttpRequest.RequestHeaders and HttpRequest.ResponseHeaders policy request attributes. Update existing policies or Trust Framework entities that refer to HttpRequest.Headers to refer to HttpRequest.RequestHeaders.
SCIM 2 requests now include the resource type in the service value during policy processing. For example, for a glossary:gSCIM[ 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 the core section of the Policy Administration GUI’s configuration called AttributeProcessing.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.