Upgrade considerations - PingDirectory - 9.3

PingDirectory 9.3

bundle
pingdirectory-93
ft:publication_title
PingDirectory 9.3
Product_Version_ce
PingDirectory 9.3
category
Product
pd-93
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 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).

Disabling restart scripts before starting the upgrade process is recommended

Important:

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

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

Spring compatibility

Important:

Spring configuration properties in PingDirectory suite of products admin console configuration files before PingDirectory suite of products 9.0.0.0 are not compatible with the most recent admin console bundled with 9.0.0.0 and later versions of PingDirectory suite of products because of major updates to Spring dependencies. Attempting to use these older configuration files results in the console failing to start.

If you are using older PingDirectory suite of products admin console configuration files, update them by replacing 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:

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/

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

  • This upgrade moves to Jetty 9.4. As a result, the HTTPS Connection Handler no longer supports 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.

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.

PingDataSync

Considerations when upgrading to 9.0.0.0 or later

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

If you are using older PingData admin console configuration files, these should be updated. 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.