We have just released version 22.214.171.124 of the Ping Identity Directory Server. See the release notes for a complete overview of changes, but here’s my summary:
Potential Backward Compatibility Issues
Summary of New Features and Enhancements for All Products
- Added support for Java 17 [more information]
- Added support for accessing external services through an HTTP proxy server [more information]
- Added a Prometheus monitoring servlet extension [more information]
- Added support for authenticating to Amazon AWS using an IRSA role [more information]
- Added support for generating digital signatures with encryption settings definitions [more information]
- Updated replace-certificate when running in interactive mode so that it can re-prompt for a certificate file if the initial file existed but did not contain valid certificate data
Summary of New Features and Enhancements for the Directory Server
- Improved support for data security auditors [more information]
- Added new secure, connectioncriteria, and requestcriteria access control keywords [more information]
- Added support for defining resource limits for unauthenticated clients [more information]
- Added Argon2i, Argon2d, and Argon2id password storage schemes to supplement the existing Argon2 scheme [more information]
- Changed the default value of the replication-purge-obsolete-replicas global configuration property from false to true
- Updated migrate-ldap-schema to support migrating attribute type definitions from Active Directory in spite of their non-standards-compliant format
- Improved the usage text for the dsreplication enable command
Summary of New Features and Enhancements for the Directory Proxy Server
- Exposed the maximum-attributes-per-add-request and maximum-modifications-per-modify-request properties in the global configuration
Summary of New Features and Enhancements for the Synchronization Server
- Added support for synchronizing to SCIMv2 destinations [more information]
- Added a sync-pipe-view tool that can display information about the set of sync pipes configured in the server
- Added sync pipe monitor attributes related to account password policy state when synchronizing to a Ping Identity Directory Server
Summary of Bug Fixes
- Fixed an issue that could cause replication protocol messages to be dropped, potentially resulting in paused replication
- Fixed an issue in which a timeout could prevent adding servers to a large topology
- Fixed an issue in which an unexpected error could cause a replication server to stop accepting new connections
- Fixed an issue that prevented resource limits from being set properly for the topology administrator
- Fixed an issue in which the dsreplication tool incorrectly handled DNs in a case-sensitive manner
- Fixed an issue that could cause dsreplication enable to fail if there were any topology administrators without passwords
- Fixed an issue that could cause a configured idle timeout to interfere with replica initialization
- Fixed an issue that could prevent the server from generating an administrative alert when clearing an alarm that triggered an alert when it was originally raised
- Fixed an issue that could cause degraded performance to a PingOne sync destination
- Fixed an issue that could prevent users from changing their own passwords with the password modify extended operation if their account was in a “must change password” state and the request passed through the Directory Proxy Server
- Fixed an issue in which dsconfig would always attempt to use simple authentication when applying changes to servers in a group, regardless of the type of authentication used when launching dsconfig
- Fixed an issue that could cause certain kinds of Directory REST API requests to fail if they included the uniqueness request control
- Fixed an issue in which an unclean shutdown could cause the server to create exploded index databases
- Disabled the index cursor entry limit by default, which could cause certain types of indexed searches to be considered unindexed
- Fixed an issue that could adversely affect performance in servers with a large number of virtual static groups
Removed Support for Incremental Backups
We have removed support for incremental backups. This feature was deprecated in the 126.96.36.199 release after repeated issues that could interfere with the ability to properly restore those backups. These issues do not affect full backups, which continue to be supported.
As an alternative to full or incremental backups, we recommend using LDIF exports, which are more useful and more portable than backups. They are also typically very compressible and can be taken more frequently than backups without consuming as much disk space. Further, the extract-data-recovery-log-changes tool can be used in conjunction with either LDIF exports or backups to replay changes recorded in the data recovery log since the time the LDIF export or backup was created.
Updated the Groovy Language Version
In order to facilitate support for Java 17, we have updated the library providing support for the Groovy scripting language from version 2.x to 3.x. While this should largely preserve backward compatibility, there may be some issues that could prevent existing Groovy scripted extensions from continuing to work without any problems.
The only compatibility issue that we have noticed is that the 3.x version of the Groovy support library cannot parse Java import statements that are broken up across multiple lines, like:
This was properly handled in Groovy 2.x, but the Groovy 3.x library does not appear to support this. To address the problem, you will need to update the script to put the entire import statement on a single line, like:
If you have any Groovy scripted extensions, we strongly recommend verifying them in a test environment before attempting to update production servers.
Java 17 Support
We have updated the server to support running on JVMs running Java version 17, which is the latest LTS release of the Java language. Java versions 8 and 11 also continue to be supported.
Note that Java 17 support is limited to the Directory Server, Directory Proxy Server, and Synchronization Server. Java 17 is not supported for the Metrics Engine, although it continues to be supported on Java 8 and 11.
The best way to enable Java 17 support is to have the JAVA_HOME environment variable set to the path of the Java 17 installation when installing the server using either the setup or manage-profile setup commands. It’s more complicated to switch to Java 17 for an existing instance that was originally set up on Java 8 or 11 because there are changes in the set of JVM arguments that should be used with Java 17. As such, if you want to switch to Java 17, then we recommend installing new instances and migrating the data to them.
By default, installations using Java 17 will use the garbage first garbage collection algorithm (G1GC), which is the same default as Java 11. We also support using the Z garbage collector (ZGC) on Java 17, although we have observed that it tends to consume a significantly greater amount of memory than the garbage first algorithm. While ZGC can exhibit better garbage collection performance than G1GC, if you wish to use it, we recommend configuring a smaller JVM heap size and thoroughly testing the server under load and at scale before enabling it in production environments.
HTTP Forward Proxy Support
We have updated several server components to provide support for issuing outbound HTTP and HTTPS requests through a proxy server. Updated components include:
- The Amazon Key Manager cipher stream provider
- The Amazon Secrets Manager cipher stream provider, passphrase provider, and password storage scheme
- The Azure Key Vault cipher stream provider, passphrase provider, and password storage scheme
- The PingOne pass-through authentication plugin
- The PingOne sync source and destination
- The Pwned Passwords password validator
- The SCIMv1 sync destination
- The SCIMv2 sync destination
- The Twilio alert handler and OTP delivery mechanism
- The UNBOUNDID-YUBIKEY-OTP SASL mechanism handler
To enable HTTP forward proxy support for any of these components, first, create an HTTP proxy external server configuration object with a command like:
dsconfig create-external-server \
--server-name "Example HTTP Proxy Server" \
--type http-proxy \
--set server-host-name:proxy.example.com \
You can also optionally use the basic-authentication-username and basic-authentication-passphrase-provider properties if the HTTP proxy server requires authentication.
Once the HTTP proxy external server has been created, update the target component to reference that server. For example:
dsconfig set-password-validator-prop \
--validator-name "Pwned Passwords" \
--set "http-proxy-external-server:Example HTTP Proxy Server"
Prometheus Monitoring Servlet Extension
We have added support for a new HTTP servlet extension that can be used to expose certain server metrics in a format that can be consumed by Prometheus or other monitoring systems that support the OpenMetrics data format. To enable it, add the servlet extension to the desired HTTP connection handlers and either restart the server or disable and re-enable those connection handlers. For example:
dsconfig set-connection-handler-prop \
--handler-name "HTTPS Connection Handler" \
--add "http-servlet-extension:Prometheus Monitoring" \
dsconfig set-connection-handler-prop \
--handler-name "HTTPS Connection Handler" \
By default, the server is preconfigured to expose a variety of metrics. You can customize this to remove metrics that you don’t care about, or to add additional metrics that we didn’t include by default. Any single-valued numeric monitor attribute can be exposed as a metric. You can also customize the set of labels included in metric definitions, on both a server-wide and per-metric basis.
Improved AWS Authentication Support
The server offers a number of components that can interact with Amazon Web Services components,
- A cipher stream provider that can use the Key Management Service
- A cipher stream provider, passphrase provider, and password storage scheme that can use the Secrets Manager
In the past, you could authenticate to AWS using either a secret access key or using an IAM role that is associated with the EC2 instance or EKS container in which the server is running. In the 188.8.131.52 release, we’re introducing support for authenticating with an IRSA (IAM role for service accounts) role. We are also adding support for a default credentials provider chain that can attempt to automatically identify an appropriate authentication method for cases in which the server is running in an AWS environment, or in cases where information about a secret access key is available through either environment variables or Java system properties.
To use the new authentication methods, first create an AWS external server that specifies the desired value for the authentication-method property. Then, reference that external server when creating the desired component. For example:
dsconfig create-external-server \
--server-name AWS \
--type amazon-aws \
--set authentication-method:irsa-role \
dsconfig create-cipher-stream-provider \
--provider-name KMS \
--type amazon-key-management-service \
--set enabled:true \
--set aws-external-server:AWS \
Data Security Auditor Improvements
The server offers a data security auditor framework that can be used to iterate across entries in a number of backends and examine them for potential security-related issues or items of note. In the past, we’ve offered auditors that can do the following:
- Identify entries that define access control rules
- Identify accounts that have been administratively disabled
- Identify accounts that have passwords that are expired, are about to expire, or that have not been changed in longer than a given length of time
- Identify accounts that are locked as a result of too many authentication failures, because it’s been too long since the user last authenticated, or because they did not choose a new password in a timely manner after an administrative reset.
- Identify accounts with multiple passwords
- Identify accounts with privileges assigned by real or virtual attributes
- Identify accounts encoded with a variety of weak password storage schemes, including 3DES, AES, BASE64, BLOWFISH, CLEAR, MD5, RC4, or the default variant of the CRYPT scheme
In the 9.2 release, we’ve introduced support for several new types of data security auditors, including those that can do the following:
- Identify accounts with account usability errors, warnings, and/or notices
- Identify accounts that have an activation time in the future, an expiration time in the past, or an expiration time in the near future
- Identify accounts that have passwords encoded with a deprecated password storage scheme
- Identify accounts that have not authenticated in longer than a specified period of time, or that have not ever authenticated
- Identify accounts that reference a nonexistent password policy
- Identify entries that match a given search filter
We have also updated the Server SDK so that you can create your own data security auditors to use whatever logic you want.
In addition, we have updated the locked account data security auditor so that it can identify accounts that are locked as a result of attempting to authenticate with a password that fails password validator criteria, and we have updated the weakly encoded password data security auditor so that the following schemes are also considered weak: SMD5, SHA, SSHA, and the MD5 variant of the CRYPT scheme.
Finally, we’ve introduced support for a new audit data security recurring task that you can use to have the server automatically perform an audit on a regular basis.
New Access Control Keywords
We have introduced three new access control keywords.
The secure bind rule can be used to make access control decisions based on whether the client is using a secure connection (e.g., LDAPS or LDAP with StartTLS) to communicate with the server. Using a bind rule of secure="true" indicates that the ACI only applies to clients communicating with the server over a secure connection, while secure="false" indicates that the ACI only applies to clients communicating with the server over an insecure connection.
The connectioncriteria bind rule can be used to make access control decisions based on whether the client connection matches a specified set of connection criteria. The value of the bind rule can be either the name or the DN of the desired connection criteria.
The requestcriteria target can be used to make access control decisions based on whether the operation matches a specified set of request criteria. The value of the target can be either the name or the DN of the desired request criteria.
Note that because the Server SDK provides support for creating custom types of connection and request criteria, the introduction of these last two bind rules adds support for being able to define custom access control logic if the server’s existing access control framework doesn’t support what you want.
Resource Limits for Unauthenticated Clients
The server’s global configuration includes the following configuration properties that can be used to set default resource limits that will apply to all users that don’t have specific limits set for them:
- size-limit — Specifies the maximum number of entries that can be returned for a search operation
- time-limit — Specifies the maximum length of time the server should spend processing a search operation
- idle-time-limit — Specifies the maximum length of time that a client connection may remain established without any operations in progress
- lookthrough-limit — Specifies the maximum number of entries that the server can examine in the course of processing a search operation
These properties set global defaults for all clients, including those that aren’t authenticated. However, you may want to set lower limits for unauthenticated connections than for users that are authenticated. To make that easier to accomplish, we have added the following new additional properties that specifically apply to unauthenticated clients:
By default, these properties don’t have any values, which will cause the server to inherit the value from the property that doesn’t specifically apply to unauthenticated clients (for example, if unauthenticated-size-limit is not set, then the server will use the size-limit value as the default for both authenticated and unauthenticated clients).
Improved Signature Generation
The server supports cryptographically signing log messages, backups, and LDIF exports. Previously, those signatures were always generated with MAC keys shared among other servers in the same topology. These keys are difficult to back up and restore, and the resulting signatures cannot be verified outside of the topology.
In the 184.108.40.206 release, we have updated the server so that it now generates digital signatures with encryption settings definitions. The server’s preferred definition will be used by default, but you can specify an alternative definition with the signing-encryption-settings-id property in the crypto manager configuration.
If digital signing is enabled but no encryption settings definitions are available, then a legacy topology key will continue to be used as a fallback.
Additional Argon2 Password Storage Schemes
The Argon2 key derivation function is a popular mechanism for encoding passwords, especially after it was selected as the winner of a password hashing competition in 2015. We introduced support for an ARGON2 password storage scheme in the 220.127.116.11 release.
There are actually three variants of the Argon2 algorithm:
- Argon2i — Provides better protection against side-channel attacks. The existing ARGON2 scheme uses this variant.
- Argon2d — Provides better protection against GPU-accelerated attacks.
- Argon2id — Mixes the strategies used in the Argon2i and Argon2d variants to provide a degree of protection against both types of attacks.
In the 18.104.22.168 release, we are introducing three new password storage schemes, ARGON2I, ARGON2D, and ARGON2ID, which provide explicit support for each of these variants.
Note that if you want to use the Argon2 algorithm to encode passwords, and you need to run in an environment that contains pre-22.214.171.124 servers, then you should use the existing ARGON2 scheme. The newer schemes should only be used in environments containing only servers running version 126.96.36.199 or later.
SCIMv2 Sync Destination
The Synchronization Server has included support for SCIMv1 servers as a sync destination since the 188.8.131.52 release. This support relies on an XML-based configuration to map LDAP source attributes to SCIM destination attributes.
In the 184.108.40.206 release, we’re introducing support for SCIMv2 servers as a sync destination. For this destination, all of the necessary configuration is held in the server’s configuration framework, so there is no need for a separate file with mapping information. This implementation introduces several new types of configurable components, including:
- HTTP authorization methods, which provide support for a variety of mechanisms for authenticating to HTTP-based services, including basic authentication and OAuth 2 bearer tokens (and in the latter case, you may configure either a static bearer token or have the server obtain one from an OAuth authorization server using the client_credentials grant type).
- A SCIM2 external server, which provides the SCIM service URL, authorization method, and other settings to use when interacting with the SCIMv2 service.
- SCIM2 attribute mappings, which describe how to generate SCIM attributes from the LDAP representation of a source entry.
- SCIM2 endpoint mappings, which associate a set of attribute mappings with an endpoint in the SCIMv2 server.
- The SCIM2 sync destination, which associates the SCIM2 external server and the SCIM2 endpoint mappings.
The documentation describes the process for configuring the Synchronization Server to synchronize changes to a SCIMv2 server. In addition, the config/sample-dsconfig-batch-files/configure-synchronization-to-scim2.dsconfig file provides an example that illustrates a set of changes that can be used to synchronize inetOrgPerson LDAP entries to urn:ietf:params:scim:schemas:core:2.0:UserM. SCIMv2 entries.