Connections are created and managed using a ConnectionFactory. Ldaptive provides three implementations of ConnectionFactory:
DefaultConnectionFactory opens and closes a connection for every operation it’s used to execute. This factory should be used when LDAP operations are infrequent or the cost of managing a connection pool is too high.
PooledConnectionFactory maintains a pools of connection for use with an individual operation. See the pooling guide for more details.
SingleConnectionFactory has one connection that is used for operations. Unlike the
DefaultConnectionFactory, the connection is not closed after each use. This factory opens the connection when
SingleConnectionFactory#initialize is invoked and closes the connection when
SingleConnectionFactory#close is invoked.
startTLS / LDAPS
When transmitting sensitive data to or from an LDAP it’s important to use a secure connection. To use LDAPS, specify that in the scheme:
To execute a StartTLS request immediately after the connection is opened:
In practice it is not advisable to downgrade a TLS connection, after all, you’ve already done the hard work to establish a TLS connection. In fact, many LDAP servers don’t even support the operation. The server will simply close the connection if a stopTLS request is received. Consequently ldaptive doesn’t have functions for starting and stopping TLS on an open connection. You must decide whether you wish to use startTLS before the connection is opened.
When using SSL or startTLS trust errors are very common. The client must be configured to trust the server and when performing client authentication, the server must be configured to trust the client. This sections deals with how to configure your LDAP client with the proper trust and authentication material.
Java cacerts file
You can add either the server certificate or the server certificate’s CA to the cacerts file included with your Java installation. This is the simplest solution, but be aware that it impacts the trust of all secure connections made by the JVM.
Command line options
Java supports command line options for designating both the truststore and keystore to be used for secure connections. Note that this impacts the trust of all secure connections made by the JVM.
When performing client authentication the JVM will select the first certificate in my.keystore that matches the allowed CAs supplied by the server.
If you have a implementation of javax.net.ssl.TrustManager it can be added directory to
SslConfig. Ldaptive provides several implementations which may be helpful:
- AggregateTrustManager - combines multiple trust managers allowing the use of all trust managers or any trust manager to pass validation
- DefaultTrustManager - the default JVM trust managers
- AllowAnyTrustManager - trusts any client or server
Note that if you provide both trust managers and a credential config to the SslConfig, all trust managers will be required.
Ldaptive includes several classes to make the use of keystores and X509 credentials easier. CredentialConfig implementations support loading key and trust material from both the classpath and the file system.
Use a custom truststore for startTLS connections that is located on the classpath:
Use X509 certificates for both authentication and trust that are located on the file system:
Supported certificate formats include:
Supported private key formats include:
By default the LDAPS endpoint identification algorithm is used for hostname validation. Custom validation can be done by setting a hostname verifier:
Since LDAP connections are persistent they can be disrupted in a variety of ways: server restarts, miss-behaving load balancers, network blips, etc. Because of the myriad number of ways in which an LDAP connection may suddenly stop working ldaptive provides auto-reconnect functionality. When a disconnect is detected the connection will immediately attempt to reopen. This example shows a reconnect condition that tries 5 times with a backoff.
Ldaptive provides several different strategies for connecting to multiple hosts with a single connection factory.
|attempt each URL in the order provided for each connection; the URLs are always tried in the order in which they were provided
|attempt a random URL from a list of URLs;
|attempt the next URL in the order provided for each connection; URLs are rotated regardless of connection success or failure
|queries a DNS server for SRV records and uses those records to construct a list of URLs; When configuring this strategy you must use your DNS server for
ConnectionConfig#ldapUrl in the form dns://my.server.com.
Note that all
ConnectionConfig properties apply to every host. You cannot, for instance, configure startTLS on one host and not on another.