PingDirectory

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.

Considerations when upgrading to 11.1.0.0 or later

Java considerations

We added support for Java 25. However, previous versions of the server’s config/java.properties file contain references to the security manager, which Java 25 doesn’t support. This conflict causes the server to fail on startup.

After upgrading a previous server version to 11.1, you must complete the following steps to use Java 25:

  1. In the config/java.properties file, change the value of default.java-home to the correct Java Runtime Environment for Java 25.

  2. Run bin/dsjavaproperties --initialize.

    This command overwrites the java.properties file and saves the original file as java.properties.old.

  3. Update the new java.properties file with any custom property changes, using java.properties.old as a reference.

  4. Restart the server.

SCIM considerations

We removed SCIM 1.1 and related functionality from the server. If the server uses SCIM 1.1, you must remove the servlet extensions from all HTTP connection handlers before upgrading. For example:

$ bin/dsconfig set-connection-handler-prop \
    --handler-name "HTTPS Connection Handler" \
    --remove http-servlet-extension:SCIM

Considerations when upgrading to 10.3.0.0 or later

Custom Server SDK extensions using Java EE packages in the javax namespace

Several components were upgraded in version 10.3 of the PingDirectory suite of products. If any of your custom Server SDK extensions have classes that import javax.* packages that are part of the Java EE specification, you must migrate them to the equivalent jakarta.* packages and then recompile the extensions.

javax.* packages that are part of standard Java SE are unaffected and don’t require migration. Learn more in the Jakarta EE GitHub documentation.

Java considerations

Support for Java 11 has been removed, and upgrading to Version 10.3 of PingDirectory, PingDirectoryProxy, or PingDataSync 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.

Updating 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.

Updating 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. For more information, see 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.

Behavior change for empty arrays relative to JSON attributes

If a JSON attribute in a SCIM PATCH request contains or is an empty array, the server now clears the array. In previous versions of PingDirectory, this request doesn’t modify the existing array.

This update might cause behavior changes.

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 guidelines.

Considerations when upgrading to 9.0.0.0 or later

Because of major updates to Spring dependencies, Spring configuration properties in the admin console configuration files for the PingDirectory suite of products earlier than version 9.0.0.0 are not compatible with the admin 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/