Upgrade considerations - PingDirectory - 10.0

PingDirectory 10.0

bundle
pingdirectory-100
ft:publication_title
PingDirectory 10.0
Product_Version_ce
PingDirectory 10.0
category
Product
pd-100
pingdirectory
ContentType_ce

When upgrading your server, there are multiple upgrade scenarios with different implications that you need to consider.

Click the following tabs to see considerations for the upgrades you want to perform.

PingDirectory, PingDirectoryProxy, and PingDataSync

Consider the following when upgrading the PingDirectory suite of products.

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
Note:

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.

Important:

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.

Important:

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

Important:

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

PingDirectory and PingDirectoryProxy

The following content provides a brief description of the upgrade process and considerations that might affect your upgrade decisions.

Important:

If you plan to upgrade servers using a mixed-version environment where one version is earlier than 7.0 and some of the servers are still using the admin backend while others have been updated to the topology registry, do not attempt to make size changes to the topology. You cannot remove any existing servers (using dsreplication disable) or add new servers (using dsreplication enable) when in this transitional state of partially-updated servers. When a topology has been completely migrated to a 7.0 or later version with the topology registry, changes to the topology size are allowed, even in mixed-version environments (for example, mixed 7.3 and 8.3).

Overview

For the upgrade process, you must download and extract a new version of the PingDirectory server .zip file on the server that will be updated. In addition, you must run the update command with the --serverRoot or -R option value from the new root server pointing to the installation that will be upgraded.

Considerations

Consider the following when planning for and upgrading replicating servers:

  • The upgrading process affects only the server being upgraded. The process does not alter the configuration of other servers.
  • The update command verifies that the Java version installed meets the new server requirements. Before running the command, install the Java version that is supported by the new server.
  • For precautionary measures, back up the user data userRoot before an upgrade. Restoring from a backup might be necessary if all other servers in the replication topology have been upgraded, and a database or encoding change in the new server version prevents the database from being used with the older server version. The update and revert-update commands issue a warning when this is the case.
  • Temporarily raise the replication purge delay for all servers in the topology to cover the expected downtime for maintenance. This results in a temporary increase in disk usage for the replicationChanges database stored in <server-root>/changelogDb.
  • Replication does not need to be disabled on a server before an upgrade.
  • Make sure upgraded servers are working as expected before upgrading the last server in the topology.
  • After all replicating servers are upgraded, enable new features.
Tip:

For additional considerations, see Planning your upgrade.

Upgrade considerations introduced in PingDirectory 9.x

Keep in mind the following upgrade considerations introduced in PingDirectory 9.x versions.

Important:

If you plan to upgrade servers using a mixed-version environment where one version is earlier than 7.0 and some of the servers are still using the admin backend while others have been updated to the topology registry, do not attempt to make size changes to the topology. You cannot remove any existing servers (using dsreplication disable) or add new servers (using dsreplication enable) when in this transitional state of partially-updated servers. When a topology has been completely migrated to a 7.0 or later version with the topology registry, changes to the topology size are allowed, even in mixed-version environments (for example, mixed 7.3 and 8.3).

Permissive Modify no longer enabled by default in Directory REST API

Important:

In previous versions, Permissive Modify behavior was enabled by default for all API modify (PATCH) requests. In version 9.3, this behavior is controlled by an always-use-permissive-modify configuration parameter, which now has a default value of false. If you see a change in your application's behavior as a result of this default configuration, you can re-enable Permissive Modify by changing the value of the configuration parameter to true with bin/dsconfig.

Enabling Permissive Modify behavior affects operations like removing an attribute that does not exist, or adding a duplicate value to a single-value attribute, by returning a "success" response without actually modifying the underlying data. Having the always-use-permissive-modify configuration parameter set to false by default will return "failure" responses for such permissive operations.

Enabling replication-purge-obsolete-replicas

Warning:

The following requirement applies when upgrading from a version earlier than 9.2 to version 9.2 or higher:

You must set the replication-purge-obsolete-replicas global configuration property to true on each server in the topology before beginning the upgrade process. Failure to do so could result in a server entering lockdown mode over missing changes from an obsolete replica.

Learn more about Discovering obsolete replicas or Purging obsolete replicas.

Cleaning replication history

When cleaning replication history from a PingDirectory server, you must now use the new remove-defunct-server argument --performLocalCleanup. If you have existing automation around disaster recovery, the previous method of running remove-defunct-server without bind credentials no longer performs this replication cleanup step. For PingDirectory versions 9.0.0.0 and later, update any existing automation to use the --performLocalCleanup flag.

Upgrade considerations introduced in PingDirectory 8.x

Keep in mind the following upgrade considerations introduced in PingDirectory 8.x versions.

Important:

If you plan to upgrade servers using a mixed-version environment where one version is earlier than 7.0 and some of the servers are still using the admin backend while others have been updated to the topology registry, do not attempt to make size changes to the topology. You cannot remove any existing servers (using dsreplication disable) or add new servers (using dsreplication enable) when in this transitional state of partially-updated servers. When a topology has been completely migrated to a 7.0 or later version with the topology registry, changes to the topology size are allowed, even in mixed-version environments (for example, mixed 7.3 and 8.3).

Upgrade considerations introduced in 8.3.0.0

  • RFC 8996 was released, officially deprecating the TLSv1 and TLSv.1.1 protocols and explicitly stating that these must not be used. Per this specification, only TLSv1.2 and TLSv1.3 are considered acceptable for use. Therefore, for this release, TLSv1 and TLSv.1.1 are disabled by default. Disabling support for TLSv1 and TLSv1.1 does not prevent these protocols from being used, it only disables them by default. Support for these legacy protocols can be re-enabled in the configuration if necessary. Also, support for TLS cipher suites that use the SHA-1 message digest is being deprecated, as SHA-1 is no longer considered secure. We are also deprecating support for TLS cipher suites that use RSA key exchange because these do not provide forward secrecy.

  • Changes to entries made by the clients using the SCIMv2 API will now have the actual user ID, making the request stored in the access and audit logs. By default, the server will continue to use the "SCIM2 Servlet" user as the authorization identity for all SCIM2 requests, and the DN of this user will be recorded in the access log and in the creatorsName and modifiersName attributes. If you want to change this behavior, change the value of the map-access-tokens-to-local-users property from disabled to either optional or required. This will cause the server to map the token to a local user, and if the mapping is successful, the mapped user's DN will be used as the authorization identity for the operations.

Upgrade considerations introduced in 8.1.0.0

  • If you have upgraded a server that is in a cluster (that 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 can create temporary clusters based on server versions and modify the cluster name appropriately on each of the servers to minimize the impact while you are upgrading.

  • The bypass-pw-policy privilege was intended to provide a way for administrators to bypass certain password restrictions that would normally be imposed when managing passwords for other users. A user with this privilege could use it to bypass password validation for their own entry. The bypass-pw-policy privilege now only applies when changing another user’s password (that is, an administrative password reset), and only in the following scenarios:
    • A user with this privilege will be permitted to set pre-encoded passwords.
    • A user with this privilege will be permitted to set passwords that would otherwise be rejected by one or more password validators.
    • A user with this privilege will be permitted to set passwords that match the current password or that are in the password history.
    The privilege will only apply when changing the password for another user, and it will have no effect for a self-password change. Further, a user with this privilege will no longer be exempted from any other restrictions in their own password policy. Before upgrading, you should search for users that have the bypass-pw-policy
  • Missing changes will now be detected when the backend is reverted and there are insufficient changes in the changelog database. When in this particular missing-changes state the local replica will not accept changes from the local replication server. You can use the existing password validators and a custom password policy to enforce passwords for administrative users.
  • Fixed an issue in which the server could incorrectly evaluate a matched values request control containing an extensible match filter that specified both an attribute type and a matching rule. The server incorrectly used the attribute type's equality matching rule instead of the matching rule specified in the filter.
  • Updated the "delay bind response" failure lockout action to provide an option to delay the response to bind requests initiated by non-LDAP clients (for example, when using HTTP basic authentication). This option is disabled by default because delaying the bind response for non-LDAP clients might require temporarily blocking the thread used to process the request, which could increase the risk of a denial-of-service attack. To help mitigate this risk, if you enable delayed bind responses for non LDAP clients, we recommend that you also increase the number of request handler threads for all enabled HTTP connection handlers.
  • Updated setup to create a second encryption settings definition if data encryption is enabled. It will continue to create a definition for 128-bit AES encryption for use as the preferred definition to preserve backward compatibility with existing servers in the topology, but it will now also generate a definition for 256-bit AES encryption. The 256-bit AES definition might become the preferred definition in a future release, but you can use it now by first ensuring that any existing instances are updated to contain the new definition (with the encryption-settings export and encryption-settings import commands) and then making it the preferred definition (with encryption-settings set-preferred) in all instances.
  • Fixed an issue that could prevent the uninstaller from removing information about the instance from the topology registry.

Delegated Admin

Consider the following points when upgrading your version of Delegated Admin.

Considerations

Note:

If you're running Delegated Admin 3.5 or earlier, upgrade it to the latest version to use PingDirectory 8.0 or later.

For information about the compatibility between Delegated Admin and PingDirectory server versions, see the Compatibility matrix.

Upgrade considerations introduced in Delegated Admin 4.9

The default OpenID Connect (OIDC) grant type used by the dadmin client has been updated to Authorization Code with PKCE. The Delegated Admin application will continue to function normally with the Implicit grant type.

If you want to switch to Authorization Code with PKCE, see Changing the default OIDC grant type.

Upgrade considerations introduced in Delegated Admin 4.8

Two new permissions that affect user resource types have been added in Delegated Admin 4.8:

  • Update-profile grants the ability to update user profiles without allowing password-related privileges.
  • Reset-password grants the permission to reset passwords without the ability to change other user attributes.

To preserve current admin rights, no action is required after you upgrade.

For more information, see Configuring delegated administrator rights on the PingDirectory server.

Upgrade considerations introduced in Delegated Admin 4.6

To use the functionality that allows a help desk agent to trigger a password reset for a user, you must enable the Modifiable Password Policy State plugin on the PingDirectory server that serves as a resource backend.

To enable the Initiate Password Reset menu option on user entries, perform the following steps:

  1. Run the following command to enable the plugin needed for triggering Initiate Password Reset:
    dsconfig set-plugin-prop \
    --plugin-name "Modifiable Password Policy State Plugin" \
    --set enabled:true --set "base-dn:${searchbasedn}" \
    --set "filter:(|(objectClass=person)(objectClass=ds-cfg-user))"
    
  2. Run the following command to add a Delegated Admin attribute to the users rest type for ds-pwp-modifiable-state-json:
    dsconfig create-delegated-admin-attribute \
    --type-name users  \
    --attribute-type ds-pwp-modifiable-state-json  \
    --set "display-name:Modifiable Password Policy State"  \
    --set display-order-index:9999 
Note:

When you install Delegated Admin 4.6 using the delegated-admin.dsconfig script, the Modifiable Password Policy State plugin is enabled. If you're upgrading from a previous version of Delegated Admin, you must manually enable the plugin and add the ds-pwp-modifiable-state-json attribute as a Delegated Admin attribute.