LDAP SDK for Java

Creating and Using LDAP Connections

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.

Creating LDAP Connections

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:

• LDAPConnection()
• LDAPConnection(LDAPConnectionOperations connectionOptions)
• LDAPConnection(SocketFactory socketFactory)
• LDAPConnection(SocketFactory socketFactory, LDAPConnectionOptions connectionOptions)

Constructors which establish an unauthenticated connection:

• LDAPConnection(String host, int port)
• LDAPConnection(LDAPConnectionOperations connectionOptions, String host, int port)
• LDAPConnection(SocketFactory socketFactory, String host, int port)
• LDAPConnection(SocketFactory socketFactory, LDAPConnectionOptions connectionOptions, String host, int port)

Constructors which can establish an authenticated connection:

• LDAPConnection(String host, int port, String bindDN, String password)
• LDAPConnection(LDAPConnectionOptions connectionOptions, String host, int port, String bindDN, String password)
• LDAPConnection(SocketFactory socketFactory, String host, int port, String bindDN, String password)
• LDAPConnection(SocketFactory socketFactory, LDAPConnectionOptions connectionOptions, String host, int port, String bindDN, String password)

LDAP Connection Options

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:

• Whether a connection should attempt to automatically reconnect if the connection is unexpectedly lost.
  
  
• Whether a connection should attempt to automatically follow referrals returned from the server.
  
  
• A maximum timeout for attempting to establish a connection.
  
  
• A maximum timeout for waiting for operation responses.
  
  
• Socket options, like SO_KEEPALIVE, SO_LINGER, SO_REUSEADDR, and TCP_NODELAY.
  
  
• A mechanism for handling unsolicited notifications from the directory server.
  
  
• A mechanism for being notified when a connection is closed.
  
  

Creating SSL-Based Connections

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 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.

Connecting Unestablished Connections

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:

• connect(String host, int port)
• connect(String host, int port, int timeout)

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.

Closing Connections

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.