PingDirectory

PingDirectory and PingDirectoryProxy

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

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.

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.

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

The use of any such script is discouraged under most circumstances, as they could lead to data corruption, data loss, or result in failed upgrades. In addition, troubleshooting any issues that arise during or after the upgrade becomes considerably more challenging in the presence of these scripts.

Permissive Modify no longer enabled by default in Directory REST API

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

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.

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.

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.