The fundamental mechanism for interacting with LDAP directory servers is the com.unboundid.ldap.sdk.LDAPConnection object. It maintains a socket for communicating with the server, maintains basic session state information, and provides methods for performing LDAP operations.
The LDAPConnection class has a number of constructors. Some of them may be used to create a new connection that isn't actually connected to any server. Others may be used to establish an unauthenticated connection, and still others may be used to establish connections and perform simple authentication.
Constructors which do not establish any connection:
Constructors which establish an unauthenticated connection:
Constructors which can establish an authenticated connection:
The com.unboundid.ldap.sdk.LDAPConnectionOptions object provides an object which can be used to control a number of low-level behaviors for the SDK. Properties that can be configured using LDAPConnectionOptions options include:
The LDAPConnection constructors which take a javax.net.SocketFactory argument allow the connection to use special types of sockets for the underlying communication. By default, connections will use a socket factory which creates standard, clear-text connections. However, it is possible to use alternate forms of communication by specifying an alternate socket factory. If you provide a socket factory capable of creating SSL-based sockets, then the communication with the server will be secured.
The Javadoc documentation for the SSLUtil class provides a more thorough explanation of everything involved in creating connections, but the following example provides a quick demonstration of the process:
AggregateTrustManager trustManager = new AggregateTrustManager(false,
JVMDefaultTrustManager.getInstance(),
new TrustStoreTrustManager(trustStorePath, trustStorePIN,
"PKCS12", true));
SSLUtil sslUtil = new SSLUtil(trustManager);
LDAPConnectionOptions connectionOptions = new LDAPConnectionOptions();
connectionOptions.setSSLSocketVerifier(
new HostNameSSLSocketVerifier(true));
try (LDAPConnection connection = new LDAPConnection(
sslUtil.createSSLSocketFactory(), connectionOptions,
serverAddress, serverLDAPSPort))
{
// Use the connection here.
RootDSE rootDSE = connection.getRootDSE();
}
The standard way to obtain SSL-based connections is to use an instance of the javax.net.ssl.SSLSocketFactory class, perhaps one created by the getSocketFactory() method of a javax.net.ssl.SSLContext instance. This provides a great deal of flexibility and security, although it may require additional configuration to be able to trust the server certificate, or potentially to present a client certificate to the server for use in SASL EXTERNAL authentication. See the Java security documentation for information on creating SSLContext and SSLSocketFactory objects.
The UnboundID LDAP SDK for Java includes a set of classes that help make it easier to obtain socket factories for performing SSL-based communication. The com.unboundid.util.ssl.SSLUtil class provides an interface that may be used to easily create SSL socket factories (or SSL contexts for use with the StartTLS extended operation). It can be easily configured to automatically trust any certificate, obtain trust information from a key store file, or interactively prompt the user about whether to trust a given certificate. It also simplifies the process for accessing client certificates in key store files or PKCS#11 tokens.
If a connection is created with a constructor that does not actually establish a session with a target server, then one of the connect methods may be used to establish a connection to a directory server. There are two variants of this method:
If a timeout is specified, the value should be in milliseconds. If no timeout is specified, then the default connection timeout from the associated LDAPConnectionOptions object will be used.
An established connection may be closed using one of the close() methods. If the connection is not established, then no action will be taken. Otherwise, an unbind request will be sent to the server and the connection will be terminated. The connection may then be discarded, or it may be re-used by calling one of the connect methods to establish a new connection to the same or a different server.
Note that LDAPConnection objects do provide a finalize() method so that the connection will automatically be terminated if it is still established at the time that the garbage collector determines that there are no more references to it. However, it is strongly recommended that connections be explicitly closed when they are no longer needed in order to avoid the possibility of running out of available connections on the server or file descriptors on the client.