LDAP Client Configuration deprecated

This article will show you how you can configure the ldap clients the Middleware uses to make requests to ldap servers.


Starting with version 7.10.6 of the Open Xchange Server it is possible to configure individual ldap clients for various features. For example the newly created ldap contact provider. This article shows how you configure those ldap clients and which option are available.

Basic configuration

The clients (or rather the client pools) are configured via the ldap-client-config.yml yaml file. Before we go into the details of the configuration options let me show you a simple working example:

    type: simple
      trustAll: true
      address: localhost
      port: 389
    pool-min: 2
    pool-max: 10
    type: adminDN
      dn: cn=admin,dc=ox,dc=test
      password: secret

Let me explain this example. As you can see the first level separates the different ldap clients via a unique id. The ldap client is always referenced by this id. Therefore every feature using ldap clients must be configured to use the client id. See the relevant feature documentation on how to do this.

Below the client name you find two relevant configuration elements: pool on one hand and auth on the other. In the pool element you can configure all sorts of relevant attributes of the ldap client pool. For examle which type of pool to use, the size of the pool, connection properties like the connection timeout and so forth. The auth element on the other side defines how this pool authenticates against the ldap server. In the example above a simple pool with a trust all trust store is created. It connects against a local server on port 389 and creates at least 2 and maximal 10 connections. It uses admin dn to authenticate with the provided credentials.

Overview over all configuration options



The type of the connection pool.
Possible values:

  • simple - a simple connection pool to a single ldap server
  • dnsRoundRobin - a connection pool who uses dns round robin to connect to multiple ldap servers
  • roundRobin - a connection pool who uses round robin to connect to multiple ldap servers
  • fewestConnections - a connection pool who connects to the ldap server with the fewest connections
  • failover - a connection pool with connects to a single ldap server but uses others as failovers
  • readWrite - a connection pool which uses two other pools. One for read and one for write operations


An array of hosts. Each element is described with two elements: an address and an optional port. The port defaults to 10389.

Note: You can also use host instead of hosts and provide just a single element instead of an array.


The address selection mode used for a connection pool of the dnsRoundRobin type.
Possible values:

  • failover - always uses the returned serves in order they are returned
  • random - uses a random address
  • round_robin - uses round robin to select the address

Defaults to random.


The cache timeout in milliseconds of resolved dns addresses. A value of zero or below indicates no caching. Defaults to -1. This option is only viable for the dnsRoundRobin type.


Per default the java JNDI is used to acquire the ldap address. But if this setting is set to true then only the system dns is used. Defaults to false.


The minimal / initial number of connection in the connection pool. Defaults to 5.


The maximum number of connections in the connection pool. Defaults to 20.


Whether to abandon requests which run into a timeout. Defaults to false.


Whether to use the SO_KEEPALIVE socket option or not. Defaults to true.


Whether to use the TCP_NODELAY socket option or not. Default to true.


Set to true to retry failed operations with a new connection in case the failed operation indicates that the connection is not usable anymore. Defaults to false.


Whether to send request synchronous or not. Defaults to true.


Whether to automatically follow referrals or not. Default to false.


Whether to create a connection if necessary rather than waiting for a connection to become available or not. Default to true.


The id of another connection pool to be used for read requests. Only valid for readWrite pools.


The id of another connection pool to be used for write requests. Only valid for readWrite pools.


The connection timeout in milliseconds. Defaults to 10000.


The maximal message size in bytes. Defaults to 20,971,520 (~20 MB)


In case followReferrals is set to true this limit defines the maximum hop limit. Defaults to 5.


The maximum length of time in milliseconds that a connection should be allowed to be established before terminating and re-establishing the connection. A value of zero or below means no age check. Defaults to 0.


Specifies the maximum length of time in milliseconds to wait for a connection to become available when trying to obtain a connection from the pool. A value of zero should be used to indicate that the pool should not block at all. Defaults to 0.


The response timeout in milliseconds. A value of zero or less means that no default limit should be used. Defaults to 0.


The length of time in milliseconds between periodic health checks against the available connections in this pool. Defaults to 60000.


The ssl keystore configuration.


The path to the keystore file.


The optional keystore password


The certificate alias.


The ssl truststore configuration.


Whether to use a trust all truststore or not. If set to true the truststore file is ignored.


The path to the truststore file.


The optional truststore password.


Indicates whether to reject certificates if the current time is outside the validity window for the certificate. Defaults to false.



The authentication type used to bind against the ldap server.
Possible values:

  • ANONYMOUS - anonymous authentication
  • ADMINDN - authentication using static administrative credentials
  • USERDN_RESOLVED - authentication using user individual credentials in combination with a template
  • USERDN_TEMPLATE - authentication using user individual credentials. The dn is dynamically resolved
  • OAUTHBEARER - authentication using the users oauth token


Additional options for the adminDN auth type.


The distinguished name used for authentication.


The password used for authentication.


Additional options for the USERDN_TEMPLATE auth type.


Defines the source of the user name. Possible values:

  • SESSION - the login name found in the user's session is used as-is
  • MAIL - the user's primary mail address is used
  • USERNAME - the user name is used


The template to use. Use [value] as a placeholder for the value defined by nameSource. For example: cn=[value],dc=ox,dc=test.


Additional options for the USERDN_RESOLVED auth type.


Defines the source of the user name. See userDNTemplate for possible values.


The ldap filter template to use for the dn resolve. Use [value] as a placeholder for the value defined by nameSource. For example: (&(objectClass=person)(mail=[value]))


The ldap scope to use for the dn resolve.


The auth type used for the dn discovery request. Possible values: