PingDirectory, PingDirectoryProxy, and PingDataSync

Consider the following when upgrading the PingDirectory suite of products.

After reviewing the following considerations, for upgrades of PingDirectory or PingDirectoryProxy, review these additional upgrade considerations.

Java considerations when upgrading to version 10.0

Support for Java 8 has been removed, and upgrading to Version 10.0 of PingDirectory, PingDirectoryProxy, or PingDataSync will fail unless you are running Java 11 or 17.

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 8 is no longer supported. You can’t upgrade a server instance to version 10.0 without first updating Java to a supported version.

Updating from a server running a supported version of Java

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

Updating from a server running an unsupported version of Java

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.

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 11.
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 11 java.properties file.
For this option, run:

+
```
bin/dsjavaproperties --initialize
```
1. 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.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.

Considerations when upgrading to 9.3.0.0 or later

For service accounts that use password storage schemes with high computational processing costs (for example, PBKDF2, bcrypt, scrypt, or Argon2), the server could process bind requests much slower than in previous versions.

The default root password policy for the PingDirectory suite of products uses the PBKDF2 password storage scheme.

Storing a password encoded with the PBKDF2 scheme can make it many times more expensive for an adversary to crack, but you can get even better protection by creating a very strong password stored with SSHA256.

You should create a separate password policy for your service account. Choose a fast but cryptographically strong password storage scheme, such as SSHA256, and set a very strong password according to .nist.gov/800-63-3/sp800-63b.html//[NIST guidelines].

Considerations when upgrading to 9.0.0.0 or later

Because of major updates to Spring dependencies, Spring configuration properties in the administrative console configuration files for the PingDirectory suite of products earlier than version 9.0.0.0 are not compatible with the administrative console bundled with 9.0.0.0 and later versions. Attempting to use these older configuration files will result in the console failing to start.

If you are using older admin console configuration files, you must update them. Replace the following excerpt in the old application.yml file:

spring:
  profiles.active: default
  main.show-banner: false
  thymeleaf.cache: true
  thymeleaf.prefix: classpath:/public/app/

with the following:

spring:
  profiles.active: default
  web.resources:
    # 1 year. Update the corresponding value in MvcConfig if this changes.
    cache.period: 31536000
    add-mappings: false # use our custom mappings instead of the defaults
  main:
    banner-mode: "OFF"
  thymeleaf:
    prefix: classpath:/public/app/

Considerations when upgrading to 8.2.0.0

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.