Upgrade Considerations

Important considerations for upgrading to this version of the Directory Proxy Server

  • The Delegated Admin web app now supports creation of new users. Installations created using older versions of the install script require a command like the following to be run after upgrade. The 'sn' attribute is a required attribute for inetOrgPerson entries.

    dsconfig create-delegated-admin-attribute --type-name users --attribute-type sn --set "display-name:Last Name"

    To enable user creation, one of the new configuration properties org-entry-dn or org-search-filter must be set on the Delegated Admin resource type.

What's New

These are new features for this release of the Directory Proxy Server

  • Introduced a Directory REST API to create, read, update and delete (CRUD) any object in the directory using JSON over HTTP. Compared to the SCIM-based Identity Access API (introduced in 4.0), the Directory REST API offers more capability without the configuration overhead and SCIM protocol limitations.

  • Improved user and group management in the delegated user administration web app (packaged separately.) Administrators can configure the presentation order and groupings of profile attributes, improving delegated admin usability for large user profiles. Also, delegated admins can now create new users, and add and remove entire sub-groups of users to and from groups.

  • Added support for Oracle Java JDK 11 and OpenJDK 11. Added support for RedHat 7.5, CentOS 7.5, and Ubuntu 18.04 LTS. <p> When running on JDK 11, we now configure G1GC as the default garbage collection algorithm. This eliminates long garbage collection pauses in most environments.

  • Improved event tracing across coordinating HTTP and directory servers. For example, admins can now trace requests to HTTP-based services, like the Directory REST API, through the log files to the LDAP access log of the Directory Server. All HTTP-based services (e.g. SCIM, Consent API) can be configured to accept and/or generate HTTP request headers with correlation identifiers. These identifiers are logged in trace logs, HTTP access logs, and LDAP access logs.

Known Issues/Workarounds

The following are known issues in the current version of the Directory Proxy Server

  • There are known issues when running the server with Java 11.0.0. These are addressed in Java 11.0.1. In general, when using Java 11, we recommend using the latest available release.

  • The Identity Access API has been deprecated and will not be supported in the next major release.

  • On Microsoft Windows systems, JVM arguments for verbose GC logging do not work as expected. So these arguments are not added to any of the server or client tools.

Resolved Issues

The following issues have been resolved with this release of the Directory Proxy Server:

Ticket ID Description

Updated the server to allow delaying the response to failed bind operations by a specified length of time. While the response is delayed, no other operations will be allowed on the connection. This can be used instead of, or in addition to, account lockout as a means of limiting the rate at which an attacker may try to guess user passwords.


To facilitate testing in multiple GC (garbage collection) environments, GC JVM options having been moved to separate Java properties in the java.properties file. The new ".gc-type" suffix will select the GC type to use, and the new ".gc-<GC type>-args" suffix will have the JVM options for that GC type.


Updated the server to expose information about the duration of lengthy phases of server startup. The longest phases are logged to the error log and more detail is provided in the "cn=Startup Phase Times,cn=monitor" monitor entry. Starting the server with the --verbose option will show fine-grained timing information for all phases of server startup.


Added support for a new file retention task that can identify files in an indicated directory that match a given pattern and remove any matching files that fall outside of the specified retention criteria. You can specify the minimum number of files that should be retained, the minimum age of files that should be retained, the minimum aggregate size of files that should be retained, or any combination thereof. The files that match the pattern will be sorted by timestamp so that if any files are to be removed, the most recent files will be retained and the oldest files will be deleted.

The file retention task can be scheduled as a standalone task or as a recurring task. Two instances of the file retention recurring task have been defined in the default configuration: one that can clean up old expensive operation dump files, and another that can clean up old work queue backlog thread dump files. In each case, the recurring task is configured to keep at least the 100 most recent files, and no files less than 30 days old will be removed. While these recurring tasks are defined in the out-of-the-box configuration, they are not part of any recurring task chain and therefore will not actually be invoked unless they are configured as part of a chain.

The Directory Server and Directory Proxy Server now include recurring tasks in the out-of-the-box configuration that can clean up old expensive operation dump log files or work queue backlog thread dump log files if too many of them have collected in the server logs directory. For each type of file, if there are more than 100 of them in the server logs directory, then any of the remaining files that are more than 30 days old are candidates for removal. A recurring task chain will perform this cleanup every day at 12:05 a.m. in the JVM's default time zone.


Multiple instances of the SCIM HTTP Servlet Extension may now be created, allowing for multiple SCIM 1.1 service configurations per server instance. For more information, please refer to the "Managing the SCIM Servlet Extension" chapter of the Administration Guide.


Added support for an exec task that can invoke commands on the server. There are several safeguards in place to prevent unauthorized users from invoking arbitrary commands on the server system, including a new exec-task privilege and a whitelist file that must be updated to include the absolute paths of the allowed commands. A new schedule-exec-task tool helps create an exec task from the command line, and the LDAP SDK has also been updated to allow interacting with exec tasks programmatically.


Added support for recurring exec tasks.


HTTP Connection Handlers will now raise an alarm during initialization if a context path conflict is detected.


A new --topologyFilePath argument has been added to remove-defunct-server, making it possible to remove a defunct server cleanly from the topology using one of the servers in the provided topology file. The topology file may be obtained by running the manage-topology export command.


A header containing a correlation ID is now added to outgoing HTTP servlet responses, allowing HTTP responses to be correlated with log messages across server instances. The name of the correlation ID response header defaults to "Correlation-Id" but may be changed by setting the HTTP Connection Handler's correlation-id-response-header property. By default, the server will generate a globally unique correlation ID automatically, but the correlation-id-request-header configuration property may be used to optionally specify one or more request headers that provide an existing correlation ID value from the requesting client. The correlation ID header can be disabled on a per-HTTP Connection Handler basis using the use-correlation-id-header configuration property.

For Server SDK extensions that have access to the current HttpServletRequest, the correlation ID can be retrieved as a String via the HttpServletRequest's "com.pingidentity.pingdata.correlation_id" attribute. For example: <code>(String) request.getAttribute("com.pingidentity.pingdata.correlation_id");</code>


Added a Mock Access Token Validator, which accepts access tokens without validating the authenticity of the tokens using a trusted authorization server or signing certificate. When enabled, a Mock Access Token Validator accepts bearer tokens in the form of a plain text JSON object containing an arbitrary set of claims. Mock Access Token Validators are intended for test or demonstration use only and should never be enabled in production deployments or used to access sensitive data.


Added support for a delay task, which can be used on its own or as a recurring task. It is primarily intended to be used as a spacer between other tasks, and can sleep for a specified period of time, wait for the server to be idle (that is, there are no outstanding operations and all worker threads are idle), or wait for sets of search criteria to match at least one entry (for example, until a monitor entry indicates that the server is in a desired state).


Bearer token authentication for the Consent API may now be enabled or disabled using the bearer-token-auth-enabled property of the Consent HTTP Servlet Extension.


Updated the client connection policy configuration to add a maximum-concurrent-operations-per-connection-exceeded-behavior property that specifies the behavior that the server should exhibit if a client tries to exceed the limit set by the maximum-concurrent-operations-per-connection property. Previously, any requests in excess of the maximum-concurrent-operations-per-connection limit would have been rejected with a busy result. The server now offers additional choices for the result code to use when rejecting requests (including admin limit exceeded, constraint violation, unavailable, unwilling to perform, or other), and the server can also be configured to close the connection and abandon all outstanding operations on that connection.


Updated the fewest operations load-balancing algorithm configuration to add a balance-requests-across-servers-with-same-operation-count property to specify the behavior the server should exhibit if there are multiple servers of equal preference with the same number of outstanding operations.

By default, the property has a value of true, which means that if there are multiple servers that have the same number of operations in progress, then the load-balancing algorithm will randomize the order in which those servers are selected to more evenly spread the requests across those servers.

If the property is changed to false, then the request will be sent to the first server encountered with the fewest number of operations. This will ensure that requests are routed more consistently, especially in environments with low utilization, but one server may handle a disproportionately high percentage of requests.


Updated the administrative alert health check to improve error handling and to add safeguards against the possibility of having too many active persistent searches to consume alerts from backend servers.


All tools will now enforce a minimum heap size requirement. Overriding the heap size for the system, using the --maxHeapSize argument of the dsjavaproperties tool, is only effective if the provided value is greater than the minimum required heap size for the tool.


The SCIM v1 servlet extension is no longer enabled by default for new installations. Existing installations will be unaffected on an upgrade. Customers are encouraged to use the new "Directory REST API" for REST access from now on.


Fixed an issue in which the HTTP Servlet Config Monitor could cause an exception in an HTTP Servlet Extension when attempting to determine its context paths. This caused the status tool and the Administrative Console to potentially omit the HTTP Servlet Extension from the list of active HTTP extensions.


Fixed an uncommon issue where unsuccessful searches, with a base DN below the entry balancing point, would remove the data set from the global attribute index.


Updated the Periodic Stats Logger to include columns for the average response time of operations sent to each LDAP external server.


Added a time limit retention policy to support removing log files older than a specified age.


Updated the Work Queue to increase the number of internal queues when num-queues is configured with the default of 0 (i.e., the server automatically determines the value). An internal queue is now created for every two worker threads rather than eight. This can reduce thread contention and increase throughput when under extreme load.


Added an optional "titleText" field to Consent API consent definition localization objects. This field may be used to store a localized title or summary for a consent request. A corresponding "titleText" field has also been added to consent record objects.