LDAP

This section describes the configuration and specifics related to LDAP.

Setting up LDAP over SSL/TLS

Communication between DirX Access in tier-2 and LDAP repositories in tier-3 can be protected using SSL/TLS.Note that DirX Access Server acts as a client with respect to this communication.Its communication endpoint resides in the local JRE.The following steps are required to set up LDAP over SSL/TLS:

  • Obtain key material, especially server/CA certificates related to the LDAP directories (hosting Configuration/Policy or User Repositories).

  • Import the CA or server certificates into the JRE trust store of the DirX Access Server.

  • Modify the LDAP configuration.

Generating Key Material

For details on how to obtain key material and deploy it on the directory server side, refer to the server documentation or ask the appropriate administrator.

Importing the Certificates into the JRE Trust Store

To enable DirX Access to connect correctly via SSL/TLS to the LDAP server, the certificate used by the LDAP server must be recognized as valid. A valid certificate trust chain must be used for this action.

Select the certificate or certificates to be imported as trusted certificates into the JRE trust store and obtain them in Base64-encoding with BEGIN and END markers. Based on this representation, perform the following steps (for each certificate that needs to be imported as trusted) and import them into the JREs cacerts truststore. Any utility that supports management of Java keystores (for example, the Java keytool) can be used.

In the DirX Access Services wrapper.conf configuration, provide the instructions on the JREs truststore; for example, by adding:

# Truststore for SSL/TLS client connections from server (LDAPs)
wrapper.java.additional.x=-Djavax.net.ssl.trustStore=etc/keystores/cacerts
wrapper.java.additional.x=-Djavax.net.ssl.trustStorePassword=changeme

This file can be found under {installation_folder}/Services/instances/TenantId/etc/.

Replace changeme with the applicable truststore password and replace x with applicable sequence numbers.

Modifying the LDAP Configuration

For LDAP over SSL/TLS, the access method ldaps needs to be used for the LDAP provider URLs.

Hostname Checking

Hostname checking against the content of the certificate is a standard and recommended process. However, in some deployments, it is unwanted and must be switched off. All such deployments shall be investigated and the security implications shall be explicitly known and accepted. An example of this kind of scenario is a high-availability setup for a corporate directory where multiple servers share the same cryptographic material (key pair and certificate).

To switch off hostname checking of the LDAPS connection, you can use the following instructions in the wrapper.conf file.

wrapper.java.additional.x=-Dcom.sun.jndi.ldap.object.disableEndpointIdentification=true

Replace the x with an applicable sequence number.

Multiple Application Repositories, Handling Read-Only LDAP Scenarios

By default, the DirX Access product expects the LDAP application repository to be fully accessible for both reading and writing. However, in certain deployment scenarios, two LDAP servers may be involved—one functioning as the master. If the master server goes down, the LDAP directory may switch to read-only mode, which can lead to certain features becoming unavailable, such as specific authentication methods (e.g., password, OTP methods).

It is possible to enable read-only LDAP support. However, this configuration may negatively impact the security of some authentication methods. Furthermore, certain DirX Access features, such as configuration changes, will remain non-functional for the period of time that the directory is not writable.

Enabling Read-Only LDAP Support

To enable read-only support for LDAP add the following property to the wrapper.conf configuration file of your instance: wrapper.java.additional.XX=-Dsolutions.dirx.access.support.ldap.read.only=true (Replace `XX`with the next available number in the sequence of existing properties.)

Impact on Features

Below is a list of key features affected by the inability to write to the application repository, along with the behavior when the solutions.dirx.access.support.ldap.read.only flag is enabled.

For authentication methods requiring registration (e.g., FIDO, OTP), it is not possible to register new credentials while the application repository is in read-only mode, even if the flag is enabled. Any features that involve configuration changes or saving specific user data to the application repository (e.g., Config REST API, SCIM API, automatic metadata updates) will remain non-functional until the LDAP directory is writable again.

Feature Default Behavior Behavior with solutions.dirx.access.support.ldap.read.only Enabled

General Authentication

Authentication does not work if the authenticated user has an entry in the Application Repository (due to the need to write access time and login failures).

Most authentication methods work. User data is cached, but it is not guaranteed that when the application repository is writable again, the records in cache will be saved into the repository.

Fido/WebAuthn

Registration and deregistration do not work. Authentication does not work because the user’s counter cannot be updated.

Registration and deregistration are non-functional, but authentication works. However, the protocol’s security may be compromised, as DirX Access typically stores a counter with each authentication. This counter is essential for detecting whether the authenticator has been cloned.

OTP RFC4226

Authentication does not work, as the counter needs to be incremented and saved after each authentication.

Authentication works without any obstacles. DXA Cache Server Persistence is used to store the needed data.

OTP RFC6238

Authentication does not work, as some user data is saved to the application repository.

Authentication works without reducing the security of the method.

OTP callback

Authentication does not work, as OTPs are saved to the application repository.

Authentication works. OTPs are cached and deleted from the cache once used.

Switching between LDAP servers during downtime

In case where there are multiple addresses configured for the application repository (in a space separated list in the wrapper.conf file), the DXA server can switch to the secondary server in case the primary one becomes unavailable. The DXA does not do any load balancing between multiple LDAP servers itself, it always uses the primary one (unless the servers are behind proxy), and uses the secondary only during an outage. You could potentially have even more secondary servers, and if s1 and s2 are down, DXA would switch to s3.

Internally the server can identify calls to LDAP that ended unsuccessfully due to a connection issue. You can specify the number of the subsequent errors that has to be exceeded in order for the server to switch to the secondary server. This can be configured with a system property solutions.dirx.access.max.ldap.faults. To configure this property add this line to wrapper.conf`of the instance and specify the amount of faults. (Replace `XX`with the next available number in the sequence of existing properties .) The default value is `3.

wrapper.java.additional.XX=-Dsolutions.dirx.access.max.ldap.faults=3

The server automatically tries to call the LDAP twice if it encounters fail, to avoid counting occasional errors that can happen.

If the server switches to the secondary server, it will in the background try to reconnect to the primary one, when the server is available it will be used again.

LDAP large search results limitations

LDAP directories, including DirX Directory, typically have limits on the number of results that can be returned during a search operation. This might pose a problem for cases as exporting large SUTs. DirX Access does overcome some of these limitations, like maximum search results, by leveraging paged LDAP requests.

System Properties for Paging and Maximum Results

DirX Access provides two key system properties to manage LDAP result limitations, which you can configure to align with your directory’s capabilities.

The DXA server will always search for all records of a type when listing of a type is used. The more records there is, longer it will take (for example SCIM Users endpoint). That is why limiting maximum results for the LDAP search is useful. However, beware that for example for Authorization policies this limit will also apply, so choose it accordingly.

  1. Page Size for LDAP Search Requests

    • The page size for LDAP search requests can be configured via the system property:

      • solutions.dirx.access.ldap.page.size

    • The default page size is 2048, which aligns with the default settings of the DirX Directory.

    • If your directory (e.g., Active Directory) uses a different page size (typically 1000), you should adjust this property accordingly.

  1. Maximum Search Results

    • To avoid processing excessively large results, you can set a limit on the total number of results returned from an LDAP search using the property:

      • solutions.dirx.access.ldap.max.search.results

    • By default, this is set to 10,240. If you set this value to 0, the search result size becomes unlimited.

    • It’s important to note that this limit applies after paging. For example, if your page size is 2048 and the maximum results limit is 10,000, you may actually retrieve 10,240 entries (5 pages of 2048 results).

Configuring System Properties in wrapper.conf

To apply these settings, you need to add them to the wrapper.conf configuration file. Below is an example of how to configure both the page size and maximum search results properties:

# LDAP Page Size - adjust based on your directory settings (2048 for DirX, 1000 for Active Directory)
wrapper.java.additional.XX=-Dsolutions.dirx.access.ldap.page.size=2048

# LDAP Maximum Search Results - set to 0 for unlimited or define a custom limit
wrapper.java.additional.XX=-Dsolutions.dirx.access.ldap.max.search.results=10000

Make sure to replace XX with the appropriate index for the property in the wrapper.conf file, based on your existing configuration.

Paging Limitations of the LDAP Server

Even with paging enabled, the LDAP server itself might impose limits on the total number of results. In DirX Directory, this limit is set to 16,384 entries by default. In search for users this will not only include user entries but also their credentials as separate entries. As a result, exporting large structures (like user trees) may fail unless the server configuration is adjusted. As if the limit is encountered the search will end with an exception.

Modifying DirX Directory Configuration for Large Exports

Allowing large search results should only be performed for exporting the whole User tree. This will significantly increase the time needed for listing the users across the system.

To export larger datasets (like an entire SUT with thousands of users), you need to modify the DirX Directory configuration using the dirxadm tool. Specifically, you can apply a User Policy to the account used for connecting to the LDAP repository in DirX Access.

Here’s an example of how to create or modify the User Policy for larger search limits:

// first bind as administrator, user your admin DN and password
dirxadm> bind -authentication SIMPLE -user /O=My-Company/CN=admin -password dirx
dirxadm> modify -addattr USP={USN={/O=my-company/cn=admin},SL=2048,PRSL=100000,SPL=2048}

  • USN: The distinguished name (DN) of the user for whom the policy applies.

  • SL: The maximum number of records for a single search (non-paged).

  • PRSL: The maximum number of results in a paged search. Set this value higher than the total number of entries in the subtree you want to export.

  • SPL: The maximum page size for paged results.