Phone companies have been managing directories for many decades. The Internet itself has relied on distributed directory services like DNS since the mid 1980s.

It was not until the late 1980s, however, that experts from what is now the International Telecommunications Union brought forth the X.500 set of international standards, including Directory Access Protocol. The X.500 standards specify Open Systems Interconnect (OSI) protocols and data definitions for general-purpose directory services. The X.500 standards were designed to meet the needs of systems built according to the X.400 standards, covering electronic mail services.

Lightweight Directory Access Protocol has been around since the early 1990s. LDAP was originally developed as an alternative protocol that would allow directory access over Internet protocols rather than OSI protocols, and be lightweight enough for desktop implementations. By the mid 1990s, LDAP directory servers became generally available and widely used.

Until the late 1990s, LDAP directory servers were designed primarily with quick lookups and high availability for lookups in mind. LDAP directory servers replicate data, so when an update is made, that update gets pushed out to other peer directory servers. Thus if one directory server goes down lookups can continue on other servers. Furthermore, if a directory service needs to support more lookups, the administrator can simply add another directory server to replicate with its peers.

As organizations rolled out larger and larger directories serving more and more applications, they discovered that they needed high availability not only for lookups, but also for updates. Around 2000 directories began to support multi-master replication, that is replication with multiple read-write servers. Soon thereafter the organizations with the very largest directories started to need higher update performance as well as availability.

The OpenDJ code base began in the mid 2000s, when engineers solving the update performance issue decided the cost of adapting the existing C-based directory technology for high performance updates would be higher than the cost of building a next generation, high performance directory using Java technology.

LDAP directory data is organized into entries, similar to the entries for words in the dictionary, or for subscriber names in the phone book. A sample entry follows.

dn: uid=bjensen,ou=People,dc=example,dc=com
uid: bjensen
cn: Babs Jensen
cn: Barbara Jensen
facsimileTelephoneNumber: +1 408 555 1992
gidNumber: 1000
givenName: Barbara
homeDirectory: /home/bjensen
l: Cupertino
mail: bjensen@example.com
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: person
objectClass: posixAccount
objectClass: top
ou: People
ou: Product Development
roomNumber: 0209
sn: Jensen
telephoneNumber: +1 408 555 1862
uidNumber: 1076

Barbara Jensen's entry has a number of attributes, such as uid: bjensen, telephoneNumber: +1 408 555 1862, and objectClass: posixAccount^[1]. When you look up her entry in the directory, you specify one or more attributes and values to match in the entries that come back as the result of your search. Typically the attributes you search for are indexed in the directory, so the directory server can retrieve them more quickly.^[2]

The entry also has a unique identifier, shown at the top of the entry, dn: uid=bjensen,ou=People,dc=example,dc=com. DN stands for distinguished name. No two entries in the directory have the same distinguished name.^[3]

LDAP entries are arranged hierarchically in the directory. The hierarchical organization resembles a file system on a PC or a web server, often imagined as an upside-down tree structure, looking similar to a pyramid.^[4]The distinguished name consists of components separated by commas, uid=bjensen,ou=People,dc=example,dc=com. Those components reflect the hierarchy of directory entries.

Barbara Jensen's entry is located under an entry with DN ou=People,dc=example,dc=com, an organization unit and parent entry for the people at Example.com. The ou=People entry is located under the entry with DN dc=example,dc=com, the root entry for Example.com. DC stands for domain component. The directory has other root entries, such as cn=config, under which the configuration is accessible through LDAP, and potentially others such as dc=mycompany,dc=com or o=myOrganization. Thus when you look up entries, you specify the parent entry to look under in the same way you need to know whether to look in the New York, Paris, or Tokyo phone book to find a telephone number.^[5]

You may be used to web service client server communication, where each time the web client has something to request of the web server, a connection is set up and then torn down. LDAP has a different model. In LDAP the client application connects to the server and authenticates, then requests any number of operations perhaps processing results in between requests, and finally disconnects when done.

LDAP has standardized two mechanisms for extending the kinds of operations that directory servers can perform. One mechanism involves using LDAP controls. The other mechanism involves using LDAP extended operations.

LDAP controls are information added to an LDAP message to further specify how an LDAP operation should be processed. For example, the Server Side Sort Request Control modifies a search to request that the directory server return entries to the client in sorted order. The Subtree Delete Request Control modifies a delete to request that the server also remove child entries of the entry targeted for deletion.

LDAP extended operations are additional LDAP operations not included in the original standard list. For example, the Cancel Extended Operation works like an abandon operation, but finishes with a response from the server after the cancel is complete. The StartTLS Extended Operation allows a client to connect to a server on an unsecure port, but then start Transport Layer Security negotiations to protect communications.

Both LDAP controls and extended operations are demonstrated later in this guide. OpenDJ directory server supports many LDAP controls and a few LDAP extended operations, controls and extended operations matching those demonstrated in this guide.

Unless your application performs only read operations, you should authenticate to the directory server. Some directory administrators require authentication even to read directory data.

Once you authenticate (bind), directory servers like OpenDJ make authorization decisions based on your identity. With servers like OpenDJ that support proxied authorization, once authenticated your application can also request an operation on behalf of another identity, for example the identity of the end user.

Your application therefore should have an account used to authenticate such as cn=My Killer App,ou=Apps,dc=example,dc=com. The directory administrator can then authorize appropriate access for your application, and also monitor your application's requests to help you troubleshoot problems if they arise.

Your application can use simple, password-based authentication. When you opt for password-based authentication, also use Start TLS for example to avoid sending the password as clear text over the network. If you prefer to manage certificates rather than passwords, directory servers like OpenDJ can do client authentication as well.

LDAP is a stateful protocol. You authenticate (bind), you do stuff, you unbind. The server maintains a context that lets it make authorization decisions concerning your requests. You should therefore reuse connections when possible.

You can make multiple requests without having to set up a new connection and authenticate for every request. You can issue a request and get results asynchronously, while you issue another request. You can even share connections in a pool, avoiding the overhead of setting up and tearing down connections if you use them often.

In a network built for HTTP applications, your long-lived LDAP connections can get cut by network equipment configured to treat idle and even just old connections as stale resources to reclaim.

When you maintain a particularly long-lived connection such as a connection for a persistent search, periodically perform a health check to make sure nothing on the network quietly decided to drop your connection without notification. A health check might involve reading an attribute on a well-known entry in the directory.

OpenDJ LDAP SDK offers Connections.newHeartBeatConnectionFactory() methods to ensure your ConnectionFactory serves connections that are periodically checked to detect whether they are still alive.

By the time your application makes it to production, you should know what attributes you want, so request them explicitly and request all the attributes you need in the same search. For example, if all you need is mail and cn, then specify both attributes in your SearchRequest.

The difference between a general filter (mail=*@example.com) and a good, specific filter like (mail=user@example.com) can be huge numbers of entries and enormous amounts of processing time, both for the directory server that has to return search results, and also for your application that has to sort through the results. Many use cases can be handled with short, specific filters. As a rule, prefer equality filters over substring filters.

Some directory servers like OpenDJ reject unindexed searches by default, because unindexed searches are generally far more resource intensive. If your application needs to use a filter that results in an unindexed search, then work with your directory administrator to find a solution, such as having the directory maintain the indexes required by your application.

Furthermore, always use & with ! to restrict the potential result set before returning all entries that do not match part of the filter. For example, (&(location=Oslo)(!(mail=birthday.girl@example.com))).

When you modify attributes with multiple values, for example when you modify a list of group members, replace or delete specific values individually, rather than replacing the entire list of values. Making modifications specific helps directory servers replicate your changes more effectively.

Trust the LDAP result code that your application gets from the directory server. For example, if you request a modify application and you get ResultCode.SUCCESS, then consider the operation a success rather than issuing a search immediately to get the modified entry.

The LDAP replication model is loosely convergent. In other words, the directory server can, and probably does, send you ResultCode.SUCCESS before replicating your change to every directory server instance across the network. If you issue a read immediately after a write, and a load balancer sends your request to another directory server instance, you could get a result that differs from what you expect.

The loosely convergent model also means that the entry could have changed since you read it. If needed, you can use LDAP assertions to set conditions for your LDAP operations.

If you need to determine which groups an account belongs to, request isMemberOf for example with OpenDJ when you read the account entry. Other directory servers use other names for this attribute that identifies the groups to which an account belongs.

Directory servers expose their capabilities, suffixes they support, and so forth as attribute values on the root DSE. See the section on Reading Root DSEs.

This allows your application to discover a variety of information at run time, rather than storing configuration separately. Thus putting effort into querying the directory about its configuration and the features it supports can make your application easier to deploy and to maintain.

For example, rather than hard-coding dc=example,dc=com as a suffix DN in your configuration, you can search the root DSE on OpenDJ for namingContexts, and then search under the naming context DNs to locate the entries you are looking for in order to initialize your configuration.

Directory servers also expose their schema over LDAP. The root DSE attribute subschemaSubentry shows the DN of the entry holding LDAP schema definitions. See the section, Getting Schema Information. Note that LDAP object class and attribute type names are case-insensitive, so isMemberOf and ismemberof refer to the same attribute for example.

When you use large attribute values such as photos or audio messages, consider storing the objects themselves elsewhere and keeping only a reference to external content on directory entries. In order to serve results quickly with high availability, directory servers both cache content and also replicate it everywhere.

Textual entries with a bunch of attributes and perhaps a certificate are often no larger than a few KB. Your directory administrator might therefore be disappointed to learn that your popular application stores users' photo and .mp3 collections as attributes of their accounts.

A persistent search lets your application receive updates from the server as they happen by keeping the connection open and forcing the server to check whether to return additional results any time it performs a modification in the scope of your search. Directory administrators therefore might hesitate to grant persistent search access to your application. Directory servers like OpenDJ can let you discover updates with less overhead by searching the change log periodically. If you do have to use a persistent search instead, try to narrow the scope of your search.

Directory servers also support a resource-intensive operation called server-side sorting. When your application requests a server-side sort, the directory server retrieves all the entries matching your search, and then returns the whole set of entries in sorted order. For result sets of any size server-side sorting therefore ties up server resources that could be used elsewhere. Alternatives include both sorting the results after your application receives them, and also working with the directory administrator to have appropriate browsing (virtual list view) indexes maintained on the directory server for applications that must regularly page through long lists of search results.

Directory servers like OpenDJ come with schema definitions for a wide range of standard object classes and attribute types. This is because directories are designed to be shared by many applications. Directories use unique, typically IANA-registered object identifiers (OID) to avoid object class and attribute type name clashes. The overall goal is Internet-wide interoperability.

You therefore should reuse schema definitions that already exist whenever you reasonably can. Reuse them as is. Do not try to redefine existing schema definitions.

If you must add schema definitions for your application, extend existing object classes with AUXILIARY classes of your own. Take care to name your definitions such that they do not clash with other names.

When you have defined schema required for your application, work with the directory administrator to have your definitions added to the directory service. Directory servers like OpenDJ let directory administrators update schema definitions over LDAP, so there is not generally a need to interrupt the service to add your application. Directory administrators can however have other reasons why they hesitate to add your schema definitions. Coming to the discussion prepared with good schema definitions, explanations of why they should be added, and evident regard for interoperability makes it easier for the directory administrator to grant your request.

When a directory server returns a search result, the result is not necessarily an entry. If the result is a referral, then your application should follow up with an additional search based on the URIs provided in the result.

LDAP result codes are standard and clearly defined. When you receive a Result, check the ResultCode value to determine what action your application should take. When the result is not what you expect, you can also read or at least log the message string from ResultCode.getDiagnosticMessage().

If you can read the directory server access log, then you can check what the server did with your application's request. For example, the following OpenDJ access log excerpt shows a successful connection from cn=My Killer App,ou=Apps,dc=example,dc=com performing a simple bind after Start TLS, and then a simple search before unbind. The lines are wrapped for readability, whereas in the log each record starts with the time stamp.

[20/Apr/2012:13:31:05 +0200] CONNECT conn=5
 from=127.0.0.1:51561 to=127.0.0.1:1389 protocol=LDAP
[20/Apr/2012:13:31:05 +0200] EXTENDED REQ conn=5 op=0 msgID=1 name="StartTLS"
 oid="1.3.6.1.4.1.1466.20037"
[20/Apr/2012:13:31:05 +0200] EXTENDED RES conn=5 op=0 msgID=1 name="StartTLS"
 oid="1.3.6.1.4.1.1466.20037" result=0 etime=0
[20/Apr/2012:13:31:07 +0200] BIND REQ conn=5 op=1 msgID=2 version=3 type=SIMPLE
 dn="cn=My Killer App,ou=Apps,dc=example,dc=com"
[20/Apr/2012:13:31:07 +0200] BIND RES conn=5 op=1 msgID=2 result=0
 authDN="cn=My Killer App,ou=Apps,dc=example,dc=com" etime=1
[20/Apr/2012:13:31:07 +0200] SEARCH REQ conn=5 op=2 msgID=3
 base="dc=example,dc=com" scope=wholeSubtree
 filter="(uid=kvaughan)" attrs="isMemberOf"
[20/Apr/2012:13:31:07 +0200] SEARCH RES conn=5 op=2 msgID=3
 result=0 nentries=1 etime=6
[20/Apr/2012:13:31:07 +0200] UNBIND REQ conn=5 op=3 msgID=4
[20/Apr/2012:13:31:07 +0200] DISCONNECT conn=5 reason="Client Unbind"

Notice that each operation type is shown in upper case, and that the server tracks both the connection (conn=5), operation (op=[0-3]), and message ID (msgID=[1-4]) numbers to make it easy to filter records. The etime refers to how long the server worked on the request in milliseconds. Result code 0 corresponds to ResultCode.SUCCESS, as described in RFC 4511.

If result codes and server logs are not enough, many network tools can interpret LDAP packets. Get the necessary certificates to decrypt encrypted packet content.

OpenDJ LDAP SDK provides a set of modern, developer-friendly Java APIs as part of the OpenDJ product suite. The product suite includes the client SDK alongside command-line tools and sample code, a 100% pure Java directory server, and more. You can use OpenDJ LDAP SDK to create client applications for use with any server that complies with the Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map, RFC 4510.

OpenDJ LDAP SDK brings you easy-to-use connection management, connection pooling, load balancing, and all the standard LDAP operations to read and write directory entries. OpenDJ LDAP SDK also lets you build applications with capabilities defined in additional draft and experimental RFCs that are supported by modern LDAP servers.

Install an LDAP server such as OpenDJ directory server that you can use to test the applications you develop. Also, load sample data into your server. The sample data used in this guide are available in LDIF form at Example.ldif.

You can either install a build or build your own from source.

Before you either download a build of OpenDJ LDAP SDK, or get the source code to build your own SDK, make sure you have a Java Development Kit installed. See the Release Notes section on Java Environment in the Release Notes requirements.

After you install OpenDJ LDAP SDK and configure your environment as described, if you have a directory server running import sample data, and test your configuration with a sample client application.

import org.forgerock.opendj.ldap.Connection;
import org.forgerock.opendj.ldap.LDAPConnectionFactory;
import org.forgerock.opendj.ldap.SearchScope;
import org.forgerock.opendj.ldap.responses.SearchResultEntry;
import org.forgerock.opendj.ldap.responses.SearchResultReference;
import org.forgerock.opendj.ldif.ConnectionEntryReader;
import org.forgerock.opendj.ldif.LDIFEntryWriter;

//Test.java:
//Kick the SDK tires, reading Babs Jensen's entry and displaying LDIF.
//If your LDAP server is not listening on localhost:1389, or if your
//data are different change the appropriate lines below.

class Test {
    public static void main(String[] args) {

        // Create an LDIF writer which will write the search results to stdout.

        final LDIFEntryWriter writer = new LDIFEntryWriter(System.out);
        Connection connection = null;

        try {
            // Connect and bind to the server.
            // CHANGE THIS IF SERVER IS NOT AT localhost:1389.
            final LDAPConnectionFactory factory =
                    new LDAPConnectionFactory("localhost", 1389);

            connection = factory.getConnection();
            // CHANGE THIS IF ANONYMOUS SEARCHES ARE NOT ALLOWED.
            // connection.bind(userName, password);

            // Read the entries and output them as LDIF.
            // CHANGE THIS IF NO uid=bjensen,ou=people,dc=example,dc=com EXISTS.
            final ConnectionEntryReader reader =
                    connection.search("dc=example,dc=com",
                            SearchScope.WHOLE_SUBTREE, "(uid=bjensen)", "*");
            while (reader.hasNext()) {
                if (reader.isEntry()) {
                    // Got an entry.
                    final SearchResultEntry entry = reader.readEntry();
                    writer.writeComment("Search result entry: "
                            + entry.getName().toString());
                    writer.writeEntry(entry);
                } else {
                    // Got a continuation reference.
                    final SearchResultReference ref = reader.readReference();
                    writer.writeComment("Search result reference: "
                            + ref.getURIs().toString());
                }
            }
            writer.flush();
        } catch (final Exception e) {
            // Handle exceptions...
            System.err.println(e.getMessage());
        } finally {
            if (connection != null) {
                connection.close();
            }
        }
    }
}

If all goes well, Test.java compiles without errors. The test program displays Babs Jensen's entry in LDIF.

$ javac Test.java
$ java Test
# Search result entry: uid=bjensen,ou=People,dc=example,dc=com
dn: uid=bjensen,ou=People,dc=example,dc=com
givenName: Barbara
objectClass: person
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: top
uid: bjensen
cn: Barbara Jensen
cn: Babs Jensen
sn: Jensen
telephoneNumber: +1 408 555 1862
roomNumber: 0209
ou: Product Development
ou: People
l: Cupertino
mail: bjensen@example.com
facsimileTelephoneNumber: +1 408 555 1992

For synchronous operations your application gets a connection from the LDAPConnectionFactory and requests operations on the connection. When finished, your application closes the connection.

final LDAPConnectionFactory factory = new LDAPConnectionFactory(host, port);
Connection connection = null;

try {
    connection = factory.getConnection();

    // Perform operations on the connection, such as connection.bind(),
    // connection.search(), connection.modify(), etc.

    } catch (final ErrorResultException e) {
        System.err.println(e.getMessage());
        System.exit(e.getResult().getResultCode().intValue());
        return;
    } finally {
        if (connection != null) {
            connection.close();
        }
    }

For asynchronous operations, your application passes a result handler to LDAPConnectionFactory.getConnectionAsync() that implements the ResultHandler<Connection> interface.

private static final class ConnectResultHandlerImpl
        implements ResultHandler<Connection> {
    @Override
    public void handleErrorResult(final ErrorResultException error) {
        ...
    }

    @Override
    public void handleResult(final Connection connection) {
        // Connect succeeded: save connection and initiate bind.
        SearchAsync.connection = connection;

        final BindRequest request =
                Requests.newSimpleBindRequest(userName, password.toCharArray());
        connection.bindAsync(request, null, new BindResultHandlerImpl());
    }
}

// Main method initiates async operations by getting a connection...
final LDAPConnectionFactory factory = new LDAPConnectionFactory(hostName, port);
factory.getConnectionAsync(new ConnectResultHandlerImpl());

...

if (connection != null) {
    connection.close();
}

When the connection result handler gets a connection, your application can pass result handlers for other operations using methods on the connection named *Async(). For most operations, your application implements ResultHandler. For searches, your application implements SearchResultHandler. The result handler is notified upon completion of the operation.

Asynchronous methods are non-blocking, returning a FutureResult whose get() method lets you retrieve the result. Your application must coordinate concurrency when you use asynchronous operations.

LDAP defines many result codes to deal with conditions other than success. The ResultCode class encapsulates the LDAP codes and additional client-side codes specific to the SDK.

Your application deals with most non-success result codes when it catches one of the LDAP SDK exceptions corresponding to the operation you requested. ErrorResultException is a common way for the SDK to indicate a non-successful result. Your application can then take remedial action based on the result code, as in the following synchronous excerpt.

final LDAPConnectionFactory factory = new LDAPConnectionFactory(host, port);
Connection connection = null;

try {
    connection = factory.getConnection();
    connection.bind(name, password);

    // Perform operations on the connection...

} catch (final ErrorResultException e) {

    // Take remedial action based on the result code...
    // e.getResult().getResultCode() returns the code for you to interpret.

} finally {
    if (connection != null) {
        connection.close();
    }
}

Also notice the methods ResultCode.getName() that provides a short, human-readable version of the result code, and Result.getDiagnosticMessage() that can also help debug problems after the fact.

You perform simple authentication by binding with the distinguished name of a user's directory entry and the user's password. For this reason simple authentication over unsecure network connections should be done only in the lab. If your real end users are providing their passwords, your application must use simple authentication only if the network is secure.

To bind using Barbara Jensen's identity and simple authentication, for example, your application would provide the DN uid=bjensen,ou=People,dc=example,dc=com with the password hifalutin.

The directory stores the password value used for simple authentication in binary form on the userPassword attribute of the entry. In other words, for the purposes of your application the password is not a string, but instead an array of bytes. Typically the directory is further configured to store only hashed values of user passwords, rather than plain text versions. Thus even if someone managed to read the stored password values, they would still have to crack the hash in order to learn the actual passwords. When your application performing simple authentication sends the password value, the directory server therefore hashes the password value, and then compares the hashed result with the value of the userPassword on the user entry. If the values match, then the directory authenticates the user. Once the user has authenticated, the directory determines authorization for operations on the connection based on the users identity.

/**
 * Authenticate over LDAP.
 */
private static void connect()
{
  final LDAPConnectionFactory factory = new LDAPConnectionFactory(
    host, port);
  Connection connection = null;

  try
  {
    connection = factory.getConnection();
    connection.bind(bindDN, bindPassword.toCharArray());
    System.out.println("Authenticated as " + bindDN + ".");
  }
  catch (final ErrorResultException e)
  {
    System.err.println(e.getMessage());
    System.exit(e.getResult().getResultCode().intValue());
    return;
  }
  finally
  {
    if (connection != null) connection.close();
  }
}

If the password values do not match, a directory might nevertheless authenticate the client application. The LDAP specifications say that in this case, however, the directory authenticates the user as anonymous, therefore no doubt with fewer rights than the normal user, and surely fewer rights than an administrator.

Simple authentication involves sending a user name and password to the directory server. To avoid sending the user name and password in the clear, you can use SSL or Start TLS.

For both SSL and Start TLS, you pass LDAP options to the connection factory in order to set an SSL context, and set whether to use Start TLS. The SSL context lets you set a trust manager to check server certificates, and also set a key manager to provide keys when the server needs to check your client certificates. In the simplest, not-so-secure case, you can set up a trust manager that trusts all certificates.

The following example is an excerpt from the OpenDJ LDAP SDK example, org.forgerock.opendj.examples.SimpleAuth.java.

private static LDAPOptions getTrustAllOptions()
  throws GeneralSecurityException
{
  LDAPOptions lo = new LDAPOptions();
  SSLContext sslContext = new SSLContextBuilder()
    .setTrustManager(TrustManagers.trustAll()).getSSLContext();
  lo.setSSLContext(sslContext);
  lo.setUseStartTLS(useStartTLS);
  return lo;
}

A more secure and extensive SSL context would include a trust manager using a trust store and trust manager methods to check server certificates. If you also want to be able to authenticate to the server using your client certificate, you would need a key manager.

The authentication over SSL or using Start TLS in the trust-all case is much like simple authentication over LDAP without connection-level security. The primary differences are that you pass the LDAPOptions to the LDAP connection factory, and that you handle the potential security exception involved in setting up the SSL context.

/**
 * Perform authentication over a secure connection, trusting all server
 * certificates.
 */
private static void trustAllConnect()
{
  Connection connection = null;

  try
  {
    final LDAPConnectionFactory factory =
        new LDAPConnectionFactory(host, port, getTrustAllOptions());
    connection = factory.getConnection();
    connection.bind(bindDN, bindPassword.toCharArray());
    System.out.println("Authenticated as " + bindDN + ".");
  }
  catch (final ErrorResultException e)
  {
    System.err.println(e.getMessage());
    System.exit(e.getResult().getResultCode().intValue());
    return;
  }
  catch (final GeneralSecurityException e)
  {
    System.err.println(e.getMessage());
    System.exit(ResultCode.CLIENT_SIDE_CONNECT_ERROR.intValue());
  }
  finally
  {
    if (connection != null)
      connection.close();
  }
}

Simple Authentication and Security Layer (SASL) provides a way to use other mechanisms for authentication such as Kerberos or Digest authentication, or even to define your own authentication mechanism. The directory server likely advertises supported SASL mechanisms in the root DSE. The follow example shows how to search OpenDJ for supported SASL mechanisms.

$ ldapsearch
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --baseDN ""
 --searchScope base
 "(objectclass=*)" supportedSASLMechanisms
dn: 
supportedSASLMechanisms: PLAIN
supportedSASLMechanisms: EXTERNAL
supportedSASLMechanisms: DIGEST-MD5
supportedSASLMechanisms: CRAM-MD5

Notice that neither the Kerberos (GSSAPI SASL) nor the Anonymous mechanism is enabled by default, though OpenDJ implements both.

In order to use a SASL mechanism to bind, your program must set up a SASLBindRequest and pass that to the bind() method of the Connection.

This section shows an example using the SASL PLAIN mechanism, which takes either a DN or a user ID to authenticate, with an optional DN or user ID as the authorization ID that identifies the user who performs operations. The SASL PLAIN mechanism itself does not secure the connection, so the example uses StartTLS. The example is provided with the OpenDJ LDAP SDK examples in org.forgerock.opendj.examples.SASLAuth.java. The following excerpt shows the core of the bind process.

try
{
  final LDAPConnectionFactory factory =
      new LDAPConnectionFactory(host, port, getTrustAllOptions());
  connection = factory.getConnection();
  PlainSASLBindRequest request =
      Requests.newPlainSASLBindRequest(authcid, passwd.toCharArray())
      .setAuthorizationID(authzid);
  connection.bind(request);
  System.out.println("Authenticated as " + authcid + ".");
}

The implementation for getTrustAllOptions(), the same as in the example above, sets up Start TLS. When you run this example with both authorization and authentication IDs, authzid and authcid, set to u:bjensen and password hifalutin, the bind is successful, and the program reaches the final line of the try block.

Authenticated as u:bjensen.

Behind the scenes, OpenDJ has the SASL PLAIN mechanism configured by default to use the Exact Match Identity Mapper to look up user IDs as uid values. If you use another directory server, you might have to configure how it maps user IDs to user entries.

For example, imagine you must write an application where users login using their email address and a password. After the user logs in, your application displays the user's full name so it is obvious who is logged in. Your application is supposed to go to the user directory both for authentication, and also to read user profile information. You are told the user directory stores user profile entries under base DN ou=People,dc=example,dc=com, that email addresses are stored on the standard mail attribute, and full names are store on the standard cn attribute.

You figure out how to authenticate from the chapter on authentication, in which you learn you need a bind DN and a password to do simple authentication. But how do you find the bind DN given the email? How do you get the full name?

The answer to both questions is that you do an LDAP search for the user's entry, which has the DN that you use to bind, and you have the server fetch the cn attribute in the results. Your search uses the following parameters.

The following code excerpt demonstrates how this might be done in a minimal command-line program.

// Prompt for mail and password.
Console c = System.console();
if (c == null) {
    System.err.println("No console.");
    System.exit(1);
}

String mail = c.readLine("Email address: ");
char[] password = c.readPassword("Password: ");

// Search using mail address, and then bind with the DN and password.
final LDAPConnectionFactory factory = new LDAPConnectionFactory(host,
        port);
Connection connection = null;
try {
    connection = factory.getConnection();

    // No explicit bind yet so we remain anonymous for now.
    SearchResultEntry entry = connection.searchSingleEntry(baseDN,
            SearchScope.WHOLE_SUBTREE, "(mail=" + mail + ")", "cn");
    DN bindDN = entry.getName();
    connection.bind(bindDN.toString(), password);

    String cn = entry.getAttribute("cn").firstValueAsString();
    System.out.println("Hello, " + cn + "!");
} catch (final ErrorResultException e) {
    System.err.println("Failed to bind.");
    System.exit(e.getResult().getResultCode().intValue());
    return;
} finally {
    if (connection != null) {
        connection.close();
    }
}

Directory servers organize entries somewhat like a file system. Directory data is often depicted as an upside-down tree.

In the figure shown above, entries are represented by the relevant parts of their DNs. The entry with DN dc=example,dc=com is the base entry for a suffix. Under the base entry, you see two organizational units, one for people, ou=People, the other for groups, ou=Groups. The entries for people include those of Babs Jensen, Kirsten Vaughan, and Sam Carter.

When you are searching for a person's entry somewhere under dc=example,dc=com, you can start from dc=example,dc=com, from ou=People,dc=example,dc=com, or if you have enough information to pinpoint the user entry and only want to look up another attribute value for example, then directly from the entry such as cn=Babs Jensen,ou=People,dc=example,dc=com. The DN of the entry where you choose to start the search is the base DN for the search.

In addition to a base DN and scope, a search request also calls for a search filter.

When you look someone up in the telephone directory, you use the value of one attribute of a person's entry (last name), to recover the person's directory entry, which has other attributes (phone number, address). LDAP works the same way. In LDAP, search requests identify both the scope of the directory entries to consider (for example, all people or all organizations), and also the entries to retrieve based on some attribute value (for example, surname, mail address, phone number, or something else). The way you express the attribute value(s) to match is by using a search filter.

LDAP search filters define what entries actually match your request. For example, the following simple equality filter says, "Match all entries that have a surname attribute (sn) value equivalent to Jensen."

(sn=Jensen)

When you pass the directory server this filter as part of your search request, the directory server checks the entries in scope for your search to see whether they match.^[7] If the directory server finds entries that match, it returns those entries as it finds them.

The example, (sn=Jensen), shows a string representation of the search filter. The OpenDJ LDAP SDK lets you express your filters as strings, or as Filter objects. In both cases, the SDK translates the strings and objects into the binary representation sent to the server over the network.

Equality is just one of the types of comparisons available in LDAP filters. Comparison operators include the following.

When taking user input, take care to protect against users providing input that has unintended consequences. OpenDJ SDK offers several Filter methods to help you. First, you can use strongly typed construction methods such as Filter.equality().

String userInput = getUserInput();
Filter filter = Filter.equality("cn", userInput);

// Invoking filter.toString() with input of "*" results in a filter
// string "(cn=\2A)".

You can also let the SDK escape user input by using a template with Filter.format() as in the following example.

String template = "(|(cn=%s)(uid=user.%s))";
String[] userInput = getUserInput();
Filter filter = Filter.format(template, userInput[0], userInput[1]);

Finally, you can explicitly escape user input with Filter.escapeAssertionValue().

String baseDN = "ou=people,dc=example,dc=com";
String userInput = getUserInput();

// Filter.escapeAssertionValue() transforms user input of "*" to "\2A".
SearchRequest request = Requests.newSearchRequest(
        baseDN, SearchScope.WHOLE_SUBTREE,
        "(cn=" + Filter.escapeAssertionValue(userInput) + "*)", "cn", "mail");

As shown in the following excerpt with a synchronous connection, you get a Connection to the directory server from an LDAPConnectionFactory.

final LDAPConnectionFactory factory = new LDAPConnectionFactory(host,
        port);
Connection connection = null;
try {
    connection = factory.getConnection();

    // Do something with the connection...
} catch (Exception e) {
    // Handle exceptions...
} finally {
    if (connection != null) {
        connection.close();
    }
}

The Connection gives you search() methods that either take parameters in the style of the ldapsearch command, or that take a SearchRequest object. If you are sure that the search only returns a single entry, you can read the entry with the searchSingleEntry() methods. If you have the distinguished name, you can use readEntry() directly.

Depending on the method you use to search, you handle results in different ways.

When you get an entry object, chances are you want to handle attribute values as objects. The OpenDJ LDAP SDK provides the Entry.parseAttribute() method and an AttributeParser with methods for a variety of attribute value types. You can use these methods to get attribute values as objects.

// Use Kirsten Vaughan's credentials and her entry.
String name = "uid=kvaughan,ou=People,dc=example,dc=com";
char[] password = "bribery".toCharArray();
connection.bind(name, password);

// Make sure we have a timestamp to play with.
updateEntry(connection, name, "description");

// Read Kirsten's entry.
final SearchResultEntry entry = connection.readEntry(name,
        "cn", "objectClass", "hasSubordinates", "numSubordinates",
        "isMemberOf", "modifyTimestamp");

// Get the entry DN and some attribute values as objects.
DN dn = entry.getName();

Set<String> cn = entry.parseAttribute("cn").asSetOfString("");
Set<AttributeDescription> objectClasses =
        entry.parseAttribute("objectClass").asSetOfAttributeDescription();
boolean hasChildren = entry.parseAttribute("hasSubordinates").asBoolean();
int numChildren = entry.parseAttribute("numSubordinates").asInteger(0);
Set<DN> groups = entry
        .parseAttribute("isMemberOf")
        .usingSchema(Schema.getDefaultSchema()).asSetOfDN();
Calendar timestamp = entry
        .parseAttribute("modifyTimestamp")
        .asGeneralizedTime().toCalendar();

// Do something with the objects.
// ...

LDAP URLs express search requests in URL form. In the directory data you can find them used as memberURL attribute values for dynamic groups, for example. The following URL from the configuration for the administrative backend lets the directory server build a dynamic group of administrator entries that are children of cn=Administrators,cn=admin data.

ldap:///cn=Administrators,cn=admin data??one?(objectclass=*)

The static method LDAPUrl.valueOf() takes an LDAP URL string and returns an LDAPUrl object. You can then use the LDAPUrl.asSearchRequest() method to get the SearchRequest that you pass to one of the search methods for the connection.

If you want to sort search results in your client application, then make sure you have enough memory in the JVM to hold the results of the search, and use one of the search methods that lets you pass in a collection of SearchResultEntrys. After the collection is populated with the results, you can sort them.

If you are on good terms with your directory administrator, you can perhaps use a server-side sort control. The server-side sort request control asks the server to sort the results before returning them, and so is a memory intensive operation on the directory server. You set up the control using ServerSideSortRequestControl.newControl(). You get the control into your search by building a search request to pass to the search method, using SearchRequest.addControl() to attach the control before passing in the request.

If your application needs to scroll through search results a page at a time, work with your directory administrator to set up the virtual list view indexes that facilitate scrolling through results.

You use the LDAP compare operation to make an assertion about an attribute value on an entry. Unlike the search operation, you must know the distinguished name of the entry in advance to request a compare operation. You also specify the attribute type name and the value to compare to the values stored on the entry.

Connection has a choice of compare methods, depending on how you set up the operation.

Check the ResultCode from CompareResult.getResultCode() for ResultCode.COMPARE_TRUE or ResultCode.COMPARE_FALSE.

The directory entry with distinguished name "" (empty string) is called the root DSE. DSE stands for DSA-Specific Entry. DSA stands for Directory Server Agent, a single directory server.

The root DSE serves to expose information over LDAP about what the directory server supports in terms of LDAP controls, auth password schemes, SASL mechanisms, LDAP protocol versions, naming contexts, features, LDAP extended operations, and so forth. The root DSE holds all the information as values of LDAP attributes. OpenDJ defines these attributes as operational. In other words, OpenDJ only returns the attributes if you either request them specifically, or request all operational attributes.

To access the list of what an OpenDJ server supports, for example, get all operational attributes from the root DSE entry as in the following excerpt.

final LDAPConnectionFactory factory = new LDAPConnectionFactory(
  host, port);
Connection connection = null;

try
{
  connection = factory.getConnection();

  // Perform an anonymous search on the root DSE.
  final SearchResultEntry entry = connection.searchSingleEntry(
      "",                         // DN is "" for root DSE.
      SearchScope.BASE_OBJECT,    // Read only the root DSE.
      "objectclass=*",            // Every object matches this filter.
      "+");                       // Return all operational attributes.

  final LDIFEntryWriter writer = new LDIFEntryWriter(System.out);
  writer.writeComment("Root DSE for LDAP server at " + host + ":" + port);
  if (entry != null) writer.writeEntry(entry);
  writer.flush();
}

Notice that by default you can access the root DSE after authenticating anonymously. When you look at the entry in LDIF, you see that supported capabilities are generally identified by object identifier (OID).

# Root DSE for LDAP server at localhost:1389
dn: 
supportedControl: 1.2.826.0.1.3344810.2.3
supportedControl: 1.2.840.113556.1.4.1413
supportedControl: 1.2.840.113556.1.4.319
supportedControl: 1.2.840.113556.1.4.473
supportedControl: 1.2.840.113556.1.4.805
supportedControl: 1.3.6.1.1.12
supportedControl: 1.3.6.1.1.13.1
supportedControl: 1.3.6.1.1.13.2
supportedControl: 1.3.6.1.4.1.26027.1.5.2
supportedControl: 1.3.6.1.4.1.42.2.27.8.5.1
supportedControl: 1.3.6.1.4.1.42.2.27.9.5.2
supportedControl: 1.3.6.1.4.1.42.2.27.9.5.8
supportedControl: 1.3.6.1.4.1.4203.1.10.1
supportedControl: 1.3.6.1.4.1.4203.1.10.2
supportedControl: 1.3.6.1.4.1.7628.5.101.1
supportedControl: 2.16.840.1.113730.3.4.12
supportedControl: 2.16.840.1.113730.3.4.16
supportedControl: 2.16.840.1.113730.3.4.17
supportedControl: 2.16.840.1.113730.3.4.18
supportedControl: 2.16.840.1.113730.3.4.19
supportedControl: 2.16.840.1.113730.3.4.2
supportedControl: 2.16.840.1.113730.3.4.3
supportedControl: 2.16.840.1.113730.3.4.4
supportedControl: 2.16.840.1.113730.3.4.5
supportedControl: 2.16.840.1.113730.3.4.9
supportedAuthPasswordSchemes: MD5
supportedAuthPasswordSchemes: SHA1
supportedAuthPasswordSchemes: SHA256
supportedAuthPasswordSchemes: SHA512
supportedAuthPasswordSchemes: SHA384
supportedSASLMechanisms: PLAIN
supportedSASLMechanisms: EXTERNAL
supportedSASLMechanisms: DIGEST-MD5
supportedSASLMechanisms: CRAM-MD5
supportedLDAPVersion: 2
supportedLDAPVersion: 3
etag: 00000000e9155ba0
pwdPolicySubentry: cn=Default Password Policy,cn=Password Policies,cn=config
supportedFeatures: 1.3.6.1.1.14
supportedFeatures: 1.3.6.1.4.1.4203.1.5.1
supportedFeatures: 1.3.6.1.4.1.4203.1.5.2
supportedFeatures: 1.3.6.1.4.1.4203.1.5.3
subschemaSubentry: cn=schema
changelog: cn=changelog
supportedTLSCiphers: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
supportedTLSCiphers: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
supportedTLSCiphers: TLS_RSA_WITH_AES_128_CBC_SHA256
supportedTLSCiphers: TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256
supportedTLSCiphers: TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256
supportedTLSCiphers: TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
supportedTLSCiphers: TLS_DHE_DSS_WITH_AES_128_CBC_SHA256
supportedTLSCiphers: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
supportedTLSCiphers: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
supportedTLSCiphers: TLS_RSA_WITH_AES_128_CBC_SHA
supportedTLSCiphers: TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA
supportedTLSCiphers: TLS_ECDH_RSA_WITH_AES_128_CBC_SHA
supportedTLSCiphers: TLS_DHE_RSA_WITH_AES_128_CBC_SHA
supportedTLSCiphers: TLS_DHE_DSS_WITH_AES_128_CBC_SHA
supportedTLSCiphers: TLS_ECDHE_ECDSA_WITH_RC4_128_SHA
supportedTLSCiphers: TLS_ECDHE_RSA_WITH_RC4_128_SHA
supportedTLSCiphers: SSL_RSA_WITH_RC4_128_SHA
supportedTLSCiphers: TLS_ECDH_ECDSA_WITH_RC4_128_SHA
supportedTLSCiphers: TLS_ECDH_RSA_WITH_RC4_128_SHA
supportedTLSCiphers: TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA
supportedTLSCiphers: TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
supportedTLSCiphers: SSL_RSA_WITH_3DES_EDE_CBC_SHA
supportedTLSCiphers: TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA
supportedTLSCiphers: TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA
supportedTLSCiphers: SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
supportedTLSCiphers: SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA
supportedTLSCiphers: SSL_RSA_WITH_RC4_128_MD5
supportedTLSCiphers: TLS_EMPTY_RENEGOTIATION_INFO_SCSV
ds-private-naming-contexts: cn=admin data
ds-private-naming-contexts: cn=ads-truststore
ds-private-naming-contexts: cn=backups
ds-private-naming-contexts: cn=config
ds-private-naming-contexts: cn=monitor
ds-private-naming-contexts: cn=schema
ds-private-naming-contexts: cn=tasks
ds-private-naming-contexts: dc=replicationChanges
supportedTLSProtocols: SSLv2Hello
supportedTLSProtocols: SSLv3
supportedTLSProtocols: TLSv1
supportedTLSProtocols: TLSv1.1
supportedTLSProtocols: TLSv1.2
numSubordinates: 1
namingContexts: dc=example,dc=com
structuralObjectClass: ds-root-dse
lastExternalChangelogCookie: 
lastChangeNumber: 0
firstChangeNumber: 0
supportedExtension: 1.3.6.1.1.8
supportedExtension: 1.3.6.1.4.1.26027.1.6.1
supportedExtension: 1.3.6.1.4.1.26027.1.6.2
supportedExtension: 1.3.6.1.4.1.26027.1.6.3
supportedExtension: 1.3.6.1.4.1.4203.1.11.1
supportedExtension: 1.3.6.1.4.1.1466.20037
supportedExtension: 1.3.6.1.4.1.4203.1.11.3
vendorName: ForgeRock AS.
vendorVersion: OpenDJ 2.5.0
hasSubordinates: true
entryDN: 
entryUUID: d41d8cd9-8f00-3204-a980-0998ecf8427e

Three key pieces of information in the entry shown above are attribute values for namingContexts (showing the base DNs under which your application can look for user data), subschemaSubentry (indicating where the LDAP schema are stored), and supportedLDAPVersion (with OpenDJ seen to support both LDAPv2 and LDAPv3).

As shown in the previous section, you can check that the root DSE attribute supportedLDAPVersion has a value of 3.

LDAPv3 has been available since 1997. Client applications built with OpenDJ SDK use LDAPv3.

The root DSE attribute subschemaSubentry shows the DN of the entry holding LDAP schema definitions. LDAP schema defines the object classes, attributes types, attribute value syntaxes, matching rules and so on that constrain entries held by the LDAP server.

The org.forgerock.opendj.ldap.schema package is devoted to constructing and querying LDAP schemas. The Schema class for example lets you readSchemaForEntry() to get the relevant schema from the subschema subentry, and then validateEntry() to check an entry your application has constructed before sending the entry to the server.

The four basic CRUD operations — create, read, update, and delete — correspond to the LDAP operations add, search, modify (or modify DN), and delete.^[8]

As a rule, your client application must be authorized to create, update, and delete directory data. Therefore to prepare to change directory data, you first get a connection, and then bind on that connection as a user who is authorized to make the changes you plan to request.

The Connection.add() methods let you provide the entry to add as an AddRequest, an Entry, or as LDIF. If the changes to make are already expressed in LDIF, then you can also use ChangeRecordReaders, ChangeRecords, and ChangeRecordWriters to handle the changes.

The following excerpt demonstrates how to add a simple user entry under ou=People,dc=example,dc=com.

// An entry to add to the directory
Entry entry = new LinkedHashMapEntry("cn=Bob,ou=People,dc=example,dc=com")
    .addAttribute("cn", "Bob")
    .addAttribute("objectclass", "top")
    .addAttribute("objectclass", "person")
    .addAttribute("objectclass", "organizationalPerson")
    .addAttribute("objectclass", "inetOrgPerson")
    .addAttribute("mail", "subgenius@example.com")
    .addAttribute("sn", "Dobbs");

final LDAPConnectionFactory factory = new LDAPConnectionFactory(host, port);
Connection connection = null;
try {
    connection = factory.getConnection();
    // Bind as a user who has the right to add entries.
    connection.bind(adminDN, adminPwd);

    connection.add(entry);

} catch (final ErrorResultException e) {
    System.err.println(e.getMessage());
    System.exit(e.getResult().getResultCode().intValue());
    return;
} finally {
    if (connection != null) {
        connection.close();
    }
}

The Connection.modify() methods let you add, replace, and delete attributes values on an entry. Either the modifications are expressed in LDIF, or you build a ModifyRequest to express the changes.

The following excerpt demonstrates how to replace one attribute value and to add another.

final LDAPConnectionFactory factory = new LDAPConnectionFactory(host, port);
Connection connection = null;
try {
    connection = factory.getConnection();
    // Bind as a user who has the right to modify entries.
    connection.bind(adminDN, adminPwd);

    // Here, entry is a user entry with DN cn=Bob,ou=People,dc=example,dc=com.
    Entry old = TreeMapEntry.deepCopyOfEntry(entry);
    entry = entry.replaceAttribute("mail", "spammer@example.com")
            .addAttribute("description", "I see the fnords.");
    ModifyRequest request = Entries.diffEntries(old, entry);

    connection.modify(request);

} catch (final ErrorResultException e) {
    System.err.println(e.getMessage());
    System.exit(e.getResult().getResultCode().intValue());
    return;
} finally {
    if (connection != null) {
        connection.close();
    }
}

The Connection.modifyDN() methods serve to rename entries and to move them around.

The following excerpt demonstrates how to rename an entry.

final LDAPConnectionFactory factory = new LDAPConnectionFactory(host, port);
Connection connection = null;
try {
    connection = factory.getConnection();
    // Bind as a user who has the right to rename entries.
    connection.bind(adminDN, adminPwd);

    // Here, entryDN contains cn=Bob,ou=People,dc=example,dc=com.
    // The second argument is the new relative distinguished name.
    connection.modifyDN(entryDN, "cn=Ted");

} catch (final ErrorResultException e) {
    System.err.println(e.getMessage());
    System.exit(e.getResult().getResultCode().intValue());
    return;
} finally {
    if (connection != null) {
        connection.close();
    }
}

If you must move rather than rename entries, have a look at the methods for ModifyDNRequest. You can get a new request by using Requests static methods.

The following excerpt demonstrates how to delete an entry with DN cn=Ted,ou=People,dc=example,dc=com.

final LDAPConnectionFactory factory = new LDAPConnectionFactory(host, port);
Connection connection = null;
try {
    connection = factory.getConnection();
    // Bind as a user who has the right to delete entries.
    connection.bind(adminDN, adminPwd);

    connection.delete("cn=Ted,ou=People,dc=example,dc=com");

} catch (final ErrorResultException e) {
    System.err.println(e.getMessage());
    System.exit(e.getResult().getResultCode().intValue());
    return;
} finally {
    if (connection != null) {
        connection.close();
    }
}

If you must delete an entire branch of entries instead of a single leaf entry, build a DeleteRequest that includes the SubtreeDeleteRequestControl, as described in the section, Subtree Delete Request Control.

Static groups enumerate user entries. Static groups can grow large. For an example, see the group entry at the end of big-group.ldif:

dn: cn=Static,ou=Groups,dc=example,dc=com
objectClass: top
objectClass: groupofnames
cn: Static
member: uid=user.0,ou=People,dc=example,dc=com
member: uid=user.1,ou=People,dc=example,dc=com
member: uid=user.2,ou=People,dc=example,dc=com
...
member: uid=user.10000,ou=People,dc=example,dc=com

To update a static group, you either add members or remove members.

The UpdateGroup example checks that the directory server supports the Permissive Modify control. With directory servers such as OpenDJ that support the LDAP Permissive Modify control, you can use the control to avoid having to determine whether a given member is already in the group before performing the operation. Instead you can simply request an add or a delete modification for the member.

final LDAPConnectionFactory factory = new LDAPConnectionFactory(host, port);
Connection connection = null;
try {
    connection = factory.getConnection();

    Collection<String> controls =
            RootDSE.readRootDSE(connection).getSupportedControls();

    final String user = "cn=Directory Manager";
    final char[] password = "password".toCharArray();
    connection.bind(user, password);

    if (controls.contains(PermissiveModifyRequestControl.OID)) {

        final ModifyRequest request = Requests.newModifyRequest(groupDN)
                .addControl(PermissiveModifyRequestControl.newControl(true))
                .addModification(modType, "member", memberDN);
        connection.modify(request);

    } else {

        /* ... */

    }

    String op = (modType == ModificationType.ADD) ? "added to" : "deleted from";
    System.out.println("The entry with DN " + memberDN + " has been "
            + op + " the group with DN " + groupDN + ".");

} catch (final ErrorResultException e) {
    System.err.println(e.getMessage());
    System.exit(e.getResult().getResultCode().intValue());
    return;
} finally {
    if (connection != null) {
        connection.close();
    }
}

If the directory server does not support the Permissive Modify control, then the example checks whether the member is present in the group by using an LDAP compare operation. If a member to be added does not yet belong to the group, the example requests an add modification. If a member to be deleted does belong to the group, the example requests a delete modification.

final LDAPConnectionFactory factory = new LDAPConnectionFactory(host, port);
Connection connection = null;
try {
    connection = factory.getConnection();

    Collection<String> controls =
            RootDSE.readRootDSE(connection).getSupportedControls();

    final String user = "cn=Directory Manager";
    final char[] password = "password".toCharArray();
    connection.bind(user, password);

    if (controls.contains(PermissiveModifyRequestControl.OID)) {

        /* ... */

    } else {

        System.out.println("Checking whether the entry with DN "
                + memberDN + " belongs to the group with DN " + groupDN
                + "...");
        final CompareRequest request =
                Requests.newCompareRequest(groupDN, "member", memberDN);
        CompareResult result = connection.compare(request);

        if (modType == ModificationType.ADD) {
            if (result.getResultCode() == ResultCode.COMPARE_FALSE) {
                System.out.println("Member does not yet belong to group."
                        + " Adding it...");
                final ModifyRequest addMember =
                        Requests.newModifyRequest(groupDN)
                            .addModification(modType, "member", memberDN);
                connection.modify(addMember);
            }
        }

        if (modType == ModificationType.DELETE) {
            if (result.getResultCode() == ResultCode.COMPARE_TRUE) {
                System.out.println("Member belongs to group."
                        + " Removing it...");
                final ModifyRequest delMember =
                        Requests.newModifyRequest(groupDN)
                            .addModification(modType, "member", memberDN);
                connection.modify(delMember);
            }
        }

    }

    String op = (modType == ModificationType.ADD) ? "added to" : "deleted from";
    System.out.println("The entry with DN " + memberDN + " has been "
            + op + " the group with DN " + groupDN + ".");

} catch (final ErrorResultException e) {
    System.err.println(e.getMessage());
    System.exit(e.getResult().getResultCode().intValue());
    return;
} finally {
    if (connection != null) {
        connection.close();
    }
}

String member1 = "uid=user1,ou=people,dc=example,dc=com";
String member2 = "uid=user1,ou=people,dc=example,dc=com";
String member3 = "uid=user1,ou=people,dc=example,dc=com";
final ModifyRequest addMember =
    Requests.newModifyRequest(groupDN)
        .addModification(modType, "member", member1, member2, member3);
connection.modify(addMember);

To try the example, download and import big-group.ldif into your directory server, and then run the sample. For example, if OpenDJ is set up to with directory manager as cn=Directory Manager, password password listening on localhost port 1389, and you run the example with arguments localhost 1389 cn=Static,ou=Groups,dc=example,dc=com uid=user.5150,ou=People,dc=example,dc=com del, the resulting output is The entry with DN uid=user.5150,ou=People,dc=example,dc=com has been deleted from the group with DN cn=Static,ou=Groups,dc=example,dc=com..

LDAP Data Interchange Format provides a mechanism to represent directory data in text format. LDIF data is typically used to initialize directory databases, but also may be used to move data between different directories that cannot replicate directly, or even as an alternative backup format. When you read OpenDJ's external change log, you get changes expressed in LDIF.

LDIF uses base64 encoding to store values that are not safe for use in a text file, including values that represent binary objects like JPEG photos and X509 certificates, but also values that hold bits of LDIF, and values that end in white space. The description in the following LDIF holds, "Space at the end of the line " for example. Notice that continuation lines shown in the excerpt of the JPEG photo value start with spaces.

dn: uid=bjensen,ou=People,dc=example,dc=com
description:: U3BhY2UgYXQgdGhlIGVuZCBvZiB0aGUgbGluZSA=
uid: bjensen
jpegPhoto:: /9j/4AAQSkZJRgABAQEASABIAAD/4gxYSUNDX1BST0ZJTEUAAQEAAAxITGlubwIQAABt
 bnRyUkdCIFhZWiAHzgACAAkABgAxAABhY3NwTVNGVAAAAABJRUMgc1JHQgAAAAAAAAAAAAAAAAAA9tY
 AAQAAAADTLUhQICAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAB
 ...
 Pxv8A8lh8J/8AXUfzr1qP/WSfWlzPlsZSi3VHqMA/WinUVB0n/9k=
facsimileTelephoneNumber: +1 408 555 1992
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: posixAccount
objectClass: top
givenName: Barbara
cn: Barbara Jensen
cn: Babs Jensen
telephoneNumber: +1 408 555 1862
sn: Jensen
roomNumber: 0209
homeDirectory: /home/bjensen
ou: Product Development
ou: People
l: Cupertino
mail: bjensen@example.com
uidNumber: 1076
gidNumber: 1000

LDIF can serve to describe not only entries with their attributes but also changes to entries. For example, you can express adding a JPEG photo to Babs Jensen's entry as follows.

dn: uid=bjensen,ou=people,dc=example,dc=com
changetype: modify
add: jpegPhoto
jpegPhoto:< file:///tmp/opendj-logo.jpg

You can also replace and delete attribute values. Notice the dash, -, used to separate changes.

dn: uid=bjensen,ou=people,dc=example,dc=com
changetype: modify
replace: roomNumber
roomNumber: 1234
-
delete: description
-
delete: jpegPhoto

LDIF also allows changetypes of add to create entries, delete to remove entries, and modrdn to rename entries.

For more examples, see the LDIF specification, RFC 2849.

OpenDJ LDAP SDK provides ChangeRecordReaders to read requests to modify directory data, and EntryReaders to read entries from a data source such as a file or other source. Both of these are interfaces.

The following short excerpt shows a reader that takes LDIF change records from standard input.

InputStream ldif = System.in;
final LDIFChangeRecordReader reader = new LDIFChangeRecordReader(ldif);

ChangeRecordWriters let you write requests to modify directory data, whereas EntryWriters let you write entries to a file or an output stream. Both of these are interfaces.

The following excerpt shows a writer pushing LDIF changes to a directory server.

final LDIFChangeRecordReader reader = new LDIFChangeRecordReader(ldif);
final LDAPConnectionFactory factory = new LDAPConnectionFactory(host, port);
Connection connection = null;

try {
    connection = factory.getConnection();
    connection.bind(userDN, password.toCharArray());

    final ConnectionChangeRecordWriter writer =
            new ConnectionChangeRecordWriter(connection);
    while (reader.hasNext()) {
        ChangeRecord changeRecord = reader.readChangeRecord();
        writer.writeChangeRecord(changeRecord);
    }
} catch (final ErrorResultException e) {
    System.err.println(e.getMessage());
    System.exit(e.getResult().getResultCode().intValue());
    return;
} catch (final IOException e) {
    System.err.println(e.getMessage());
    System.exit(ResultCode.CLIENT_SIDE_LOCAL_ERROR.intValue());
    return;
} finally {
    if (connection != null) {
        connection.close();
    }
}

Controls provide a mechanism whereby the semantics and arguments of existing LDAP operations may be extended. One or more controls may be attached to a single LDAP message. A control only affects the semantics of the message it is attached to. Controls sent by clients are termed request controls, and those sent by servers are termed response controls.

For OpenDJ, the controls supported are listed in the Administration Guide appendix, LDAP Controls in the Administration Guide. You can access the list of OIDs for supported LDAP controls by reading the supportedControl attribute of the root DSE.

$ ldapsearch
 --baseDN ""
 --searchScope base
 --port 1389
 "(objectclass=*)" supportedControl
dn: 
supportedControl: 1.2.826.0.1.3344810.2.3
supportedControl: 1.2.840.113556.1.4.1413
supportedControl: 1.2.840.113556.1.4.319
supportedControl: 1.2.840.113556.1.4.473
supportedControl: 1.2.840.113556.1.4.805
supportedControl: 1.3.6.1.1.12
supportedControl: 1.3.6.1.1.13.1
supportedControl: 1.3.6.1.1.13.2
supportedControl: 1.3.6.1.4.1.26027.1.5.2
supportedControl: 1.3.6.1.4.1.42.2.27.8.5.1
supportedControl: 1.3.6.1.4.1.42.2.27.9.5.2
supportedControl: 1.3.6.1.4.1.42.2.27.9.5.8
supportedControl: 1.3.6.1.4.1.4203.1.10.1
supportedControl: 1.3.6.1.4.1.4203.1.10.2
supportedControl: 1.3.6.1.4.1.7628.5.101.1
supportedControl: 2.16.840.1.113730.3.4.12
supportedControl: 2.16.840.1.113730.3.4.16
supportedControl: 2.16.840.1.113730.3.4.17
supportedControl: 2.16.840.1.113730.3.4.18
supportedControl: 2.16.840.1.113730.3.4.19
supportedControl: 2.16.840.1.113730.3.4.2
supportedControl: 2.16.840.1.113730.3.4.3
supportedControl: 2.16.840.1.113730.3.4.4
supportedControl: 2.16.840.1.113730.3.4.5
supportedControl: 2.16.840.1.113730.3.4.9

The following excerpt shows couple of methods to check whether the directory server supports a control.

/**
 * Controls supported by the LDAP server.
 */
private static Collection<String> controls;

/**
 * Populate the list of supported LDAP control OIDs.
 *
 * @param connection
 *            Active connection to the LDAP server.
 * @throws ErrorResultException
 *             Failed to get list of controls.
 */
static void checkSupportedControls(Connection connection)
        throws ErrorResultException {
    controls = RootDSE.readRootDSE(connection).getSupportedControls();
}

/**
 * Check whether a control is supported. Call {@code checkSupportedControls}
 * first.
 *
 * @param control
 *            Check support for this control, provided by OID.
 * @return True if the control is supported.
 */
static boolean isSupported(final String control) {
    if (controls != null && !controls.isEmpty()) {
        return controls.contains(control);
    }
    return false;
}

The LDAP assertion control lets you specify a condition that must be true in order for the operation you request to be processed normally. The following excerpt shows, for example, how you might check that no description exists on the entry before adding your description.

if (isSupported(AssertionRequestControl.OID)) {
    final String dn = "uid=bjensen,ou=People,dc=example,dc=com";

    final ModifyRequest request =
            Requests.newModifyRequest(dn)
                .addControl(AssertionRequestControl.newControl(
                        true, Filter.valueOf("!(description=*)")))
                .addModification(ModificationType.ADD, "description",
                        "Created using LDAP assertion control");

    connection.modify(request);

    final LDIFEntryWriter writer = new LDIFEntryWriter(System.out);
    try {
        writer.writeEntry(connection.readEntry(dn, "description"));
        writer.close();
    } catch (final IOException e) {
        // The writer could not write to System.out.
    }
}

OpenDJ directory server supports the LDAP assertion control:

dn: uid=bjensen,ou=People,dc=example,dc=com
description: Created using LDAP assertion control

The LDAP Authorization Identity Controls let you get the authorization identity established when you bind to the directory server. The following excerpt shows simple use of the controls.

if (isSupported(AuthorizationIdentityRequestControl.OID)) {
    final String dn = "uid=bjensen,ou=People,dc=example,dc=com";
    final char[] pwd = "hifalutin".toCharArray();

    System.out.println("Binding as " + dn);
    final BindRequest request =
            Requests.newSimpleBindRequest(dn, pwd)
                .addControl(AuthorizationIdentityRequestControl.newControl(true));

    final BindResult result = connection.bind(request);
    try {
        final AuthorizationIdentityResponseControl control =
                result.getControl(AuthorizationIdentityResponseControl.DECODER,
                        new DecodeOptions());
        System.out.println("Authorization ID returned: "
                        + control.getAuthorizationID());
    } catch (final DecodeException e) {
        // Failed to decode the response control.
    }
}

OpenDJ directory server supports the LDAP Authorization Identity Controls:

Binding as uid=bjensen,ou=People,dc=example,dc=com
Authorization ID returned: dn:uid=bjensen,ou=People,dc=example,dc=com

When performing a persistent search, your application can retrieve information using this response control about why the directory server returned the entry. See the Internet-Draft on persistent searches for background information.

if (isSupported(PersistentSearchRequestControl.OID)) {
    final SearchRequest request =
            Requests.newSearchRequest(
                    "dc=example,dc=com", SearchScope.WHOLE_SUBTREE,
                    "(objectclass=inetOrgPerson)", "cn")
                    .addControl(PersistentSearchRequestControl.newControl(
                            true, true, true, // critical,changesOnly,returnECs
                            PersistentSearchChangeType.ADD,
                            PersistentSearchChangeType.DELETE,
                            PersistentSearchChangeType.MODIFY,
                            PersistentSearchChangeType.MODIFY_DN));

    final ConnectionEntryReader reader = connection.search(request);

    try {
        while (reader.hasNext()) {
            if (!reader.isReference()) {
                final SearchResultEntry entry = reader.readEntry();
                System.out.println("Entry changed: "
                        + entry.getName().toString());

                EntryChangeNotificationResponseControl control =
                        entry.getControl(
                                EntryChangeNotificationResponseControl.DECODER,
                                new DecodeOptions());

                PersistentSearchChangeType type = control.getChangeType();
                System.out.println("Change type: " + type.toString());
                if (type.equals(PersistentSearchChangeType.MODIFY_DN)) {
                    System.out.println("Previous DN: "
                            + control.getPreviousName().toString());
                }
                System.out.println("Change number: "
                        + control.getChangeNumber());
                System.out.println(); // Add a blank line.
           }
        }
    } catch (final DecodeException e) {
        // Failed to decode the response control.
    } catch (final ErrorResultIOException e) {
        // Request failed due to an IO problem.
    } catch (final SearchResultReferenceIOException e) {
        // Read a reference, rather than an entry.
    }
}

OpenDJ directory server supports persistent searches and the entry change notification response control. When another application renames Anne-Louise Barnes's entry, the sample code picks up information from the entry change notification response control:

Entry changed: uid=bdobbs,ou=People,dc=example,dc=com
Change type: modifyDN
Previous DN: uid=abarnes,ou=People,dc=example,dc=com
Change number: -1

In this case, Change number: -1 because the server did not set a change number value. OpenDJ directory server does not set the change number value in the response control. If you need to track the order of changes with OpenDJ directory server, read the external change log instead of using the entry change notification response control.

Your application can attach the GetEffectiveRights request control to retrieve information about what the directory server permits a user to do. Use this control during a search to see permissions on the entries returned. See the Internet-Draft on the Access Control Model for LDAP for background.

if (isSupported(GetEffectiveRightsRequestControl.OID)) {
    final String authDN = "uid=kvaughan,ou=People,dc=example,dc=com";

    final SearchRequest request =
            Requests.newSearchRequest(
                    "dc=example,dc=com", SearchScope.WHOLE_SUBTREE,
                    "(uid=bjensen)", "cn", "aclRights", "aclRightsInfo")
                    .addControl(GetEffectiveRightsRequestControl.newControl(
                            true, authDN, "cn"));

    final ConnectionEntryReader reader = connection.search(request);
    final LDIFEntryWriter writer = new LDIFEntryWriter(System.out);
    try {
        while (reader.hasNext()) {
            if (!reader.isReference()) {
                final SearchResultEntry entry = reader.readEntry();
                writer.writeEntry(entry);
            }
        }
        writer.close();
    } catch (final ErrorResultIOException e) {
        // Request failed due to an IO problem.
    } catch (final SearchResultReferenceIOException e) {
        // Read a reference, rather than an entry.
    } catch (final IOException e) {
        // The writer could not write to System.out.
    }
}

OpenDJ SDK currently implements the request control, but not the response control. The results are shown as values of the aclRights and more verbose aclRightsInfo attributes.

dn: uid=bjensen,ou=People,dc=example,dc=com
aclRightsInfo;logs;attributeLevel;selfwrite_delete;cn: acl_summary(main)
 : access allowed(write) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com
 , distinguishedName) to (uid=kvaughan,ou=People,dc=example,dc=com) (not proxied
 ) ( reason: evaluated allow , deciding_aci: allow all Admin group)
aclRightsInfo;logs;entryLevel;read: acl_summary(main): access allowed(read
 ) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, objectClass) to (
 uid=kvaughan,ou=People,dc=example,dc=com) (not proxied) ( reason
 : evaluated allow , deciding_aci: Anonymous read-search access)
aclRightsInfo;logs;attributeLevel;proxy;cn: acl_summary(main)
 : access not allowed(proxy) on entry/attr(uid=bjensen,ou=People,dc=example,
 dc=com, cn) to (uid=kvaughan,ou=People,dc=example,dc=com) (not proxied
 ) (reason: no acis matched the subject )
aclRights;attributeLevel;cn: search:1,read:1,compare:1,write:1,selfwrite_add:1,
 selfwrite_delete:1,proxy:0
aclRightsInfo;logs;attributeLevel;write;cn: acl_summary(main): access allowed
 (write) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, cn) to (
 uid=kvaughan,ou=People,dc=example,dc=com) (not proxied
 ) ( reason: evaluated allow , deciding_aci: allow all Admin group)
aclRights;entryLevel: add:1,delete:1,read:1,write:1,proxy:0
aclRightsInfo;logs;attributeLevel;search;cn: acl_summary(main): access allowed(
 search) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, cn) to (
 uid=kvaughan,ou=People,dc=example,dc=com) (not proxied
 ) ( reason: evaluated allow , deciding_aci: Anonymous read-search access)
aclRightsInfo;logs;entryLevel;write: acl_summary(main): access allowed(write
 ) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, NULL) to (
 uid=kvaughan,ou=People,dc=example,dc=com) (not proxied
 ) ( reason: evaluated allow , deciding_aci: allow all Admin group)
aclRightsInfo;logs;attributeLevel;selfwrite_add;cn: acl_summary(main
 ): access allowed(write) on entry/attr(uid=bjensen,ou=People,dc=example,
 dc=com, distinguishedName) to (uid=kvaughan,ou=People,dc=example,dc=com) (
 not proxied) ( reason: evaluated allow , deciding_aci: allow all Admin group)
aclRightsInfo;logs;entryLevel;add: acl_summary(main): access allowed(add
 ) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, NULL) to (
 uid=kvaughan,ou=People,dc=example,dc=com) (not proxied
 ) ( reason: evaluated allow , deciding_aci: allow all Admin group)
aclRightsInfo;logs;attributeLevel;read;cn: acl_summary(main): access allowed(
 read) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, cn) to (
 uid=kvaughan,ou=People,dc=example,dc=com) (not proxied
 ) ( reason: evaluated allow , deciding_aci: Anonymous read-search access)
cn: Barbara Jensen
cn: Babs Jensen
aclRightsInfo;logs;entryLevel;proxy: acl_summary(main): access not allowed(
 proxy) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, NULL) to (
 uid=kvaughan,ou=People,dc=example,dc=com) (not proxied
 ) ( reason: no acis matched the subject )
aclRightsInfo;logs;attributeLevel;compare;cn: acl_summary(main): access allowed
 (compare) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, cn) to (
 uid=kvaughan,ou=People,dc=example,dc=com) (not proxied
 ) ( reason: evaluated allow , deciding_aci: Anonymous read-search access)
aclRightsInfo;logs;entryLevel;delete: acl_summary(main): access allowed(
 delete) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, NULL) to (
 uid=kvaughan,ou=People,dc=example,dc=com) (not proxied
 ) ( reason: evaluated allow , deciding_aci: allow all Admin group)

The ManageDsaIT control, described in RFC 3296, Named Subordinate References in LDAP Directories, lets your application handle references and other special entries as normal entries. Use it when you want to read from or write to reference or special entry.

if (isSupported(ManageDsaITRequestControl.OID)) {
    final String dn = "dc=ref,dc=com";

    final LDIFEntryWriter writer = new LDIFEntryWriter(System.out);
    try {
        System.out.println("Referral without the ManageDsaIT control.");
        SearchRequest request = Requests.newSearchRequest(dn,
                SearchScope.SUBORDINATES, "(objectclass=*)", "");
        final ConnectionEntryReader reader = connection.search(request);
        while (reader.hasNext()) {
            if (reader.isReference()) {
                final SearchResultReference ref = reader.readReference();
                System.out.println("Reference: " + ref.getURIs().toString());
            }
        }

        System.out.println("Referral with the ManageDsaIT control.");
        request.addControl(ManageDsaITRequestControl.newControl(true));
        final SearchResultEntry entry = connection.searchSingleEntry(request);
        writer.writeEntry(entry);
        writer.close();
    } catch (final ErrorResultIOException e) {
        // Request failed due to an IO problem.
    } catch (final SearchResultReferenceIOException e) {
        // Read a reference, rather than an entry.
    } catch (final IOException e) {
        // The writer could not write to System.out.
    }
}

OpenDJ directory server supports the ManageDsaIT Request Control. To use the example entry create a new base DN, dc=ref,dc=com before you import the data:

Referral without the ManageDsaIT control.
Reference: [ldap:///dc=example,dc=com??sub?:///dc=example,dc=com??sub?]
Referral with the ManageDsaIT control.
dn: dc=references,dc=ref,dc=com

RFC 3876, Returning Matched Values with the LDAPv3, describes a control that lets your application pass a filter in a search request getting a multivalued attribute such that the directory server only returns attribute values that match the filter.

Barbara Jensen's entry contains two common name values, Barbara Jensen and Babs Jensen. The following excerpt retrieves only the latter.

if (isSupported(MatchedValuesRequestControl.OID)) {
    final String dn = "uid=bjensen,ou=People,dc=example,dc=com";
    final SearchRequest request =
            Requests.newSearchRequest(dn, SearchScope.BASE_OBJECT,
                    "(objectclass=*)", "cn")
                    .addControl(MatchedValuesRequestControl.newControl(
                            true, "(cn=Babs Jensen)"));

    final SearchResultEntry entry = connection.searchSingleEntry(request);
    System.out.println("Reading entry with matched values request.");
    final LDIFEntryWriter writer = new LDIFEntryWriter(System.out);
    try {
        writer.writeEntry(entry);
        writer.close();
    } catch (final IOException e) {
        // The writer could not write to System.out.
    }
}

OpenDJ directory server supports the matched values request control.

Reading entry with matched values request.
dn: uid=bjensen,ou=People,dc=example,dc=com
cn: Babs Jensen

A directory server can return the Password Expired Response Control, described in the Internet-Draft Password Policy for LDAP Directories, when a bind fails because the password has expired. In order to see this, you must configure the directory to expire Barbara Jensen's password.

if (isSupported(PasswordExpiredResponseControl.OID)) {
    final String dn = "uid=bjensen,ou=People,dc=example,dc=com";
    final char[] pwd = "hifalutin".toCharArray();

    try {
        connection.bind(dn, pwd);
    } catch (final ErrorResultException e) {
        final Result result = e.getResult();
        try {
            final PasswordExpiredResponseControl control =
                    result.getControl(PasswordExpiredResponseControl.DECODER,
                            new DecodeOptions());
            if (!(control == null) && control.hasValue()) {
                System.out.println("Password expired for " + dn);
            }
        } catch (final DecodeException de) {
            // Failed to decode the response control.
        }
    }
}

OpenDJ directory server supports the Password Expired Response Control. To obtain the following output from the excerpt, you can change the default password policy configuration to set a short maximum password age, change Barbara Jensen's password, and wait for it to expire. See the OpenDJ Administration Guide procedure explaining how To Adjust the Default Password Policy in the Administration Guide for an example of how to adjust the maximum password age.

Password expired for uid=bjensen,ou=People,dc=example,dc=com

The Password Expiring Response Control, described in the Internet-Draft Password Policy for LDAP Directories, warns your application during a bind that the password used will soon expire.

if (isSupported(PasswordExpiringResponseControl.OID)) {
    final String dn = "uid=bjensen,ou=People,dc=example,dc=com";
    final char[] pwd = "hifalutin".toCharArray();

    final BindResult result = connection.bind(dn, pwd);
    try {
        final PasswordExpiringResponseControl control =
                result.getControl(PasswordExpiringResponseControl.DECODER,
                        new DecodeOptions());
        if (!(control == null) && control.hasValue()) {
            System.out.println("Password for " + dn + " expires in "
                    + control.getSecondsUntilExpiration() + " seconds.");
        }
    } catch (final DecodeException de) {
        // Failed to decode the response control.
    }
}

OpenDJ directory server supports the Password Expiring Response Control. To obtain the following output from the excerpt, you can change the default password policy configuration to set a maximum password age and a warning interval, change Barbara Jensen's password, and wait until you enter the warning interval before password expiration. See the OpenDJ Administration Guide procedure explaining how To Adjust the Default Password Policy in the Administration Guide for an example of how to adjust the maximum password age. Also set a short password-expiration-warning-interval value.

Password for uid=bjensen,ou=People,dc=example,dc=com
 expires in 237 seconds.

The Behera Internet-Draft, Password Policy for LDAP Directories, describes Password Policy Request and Response Controls. You send the request control with a request to let the directory server know that your application can handle the response control. The directory server sends the response control on applicable operations to communicate warnings and errors.

if (isSupported(PasswordPolicyRequestControl.OID)) {
    final String dn = "uid=bjensen,ou=People,dc=example,dc=com";
    final char[] pwd = "hifalutin".toCharArray();

    try {
        final BindRequest request = Requests.newSimpleBindRequest(dn, pwd)
                .addControl(PasswordPolicyRequestControl.newControl(true));

        final BindResult result = connection.bind(request);

        final PasswordPolicyResponseControl control =
                result.getControl(PasswordPolicyResponseControl.DECODER,
                        new DecodeOptions());
        if (!(control == null) && !(control.getWarningType() == null)) {
            System.out.println("Password policy warning "
                    + control.getWarningType().toString() + ", value "
                    + control.getWarningValue() + " for " + dn);
        }
    } catch (final ErrorResultException e) {
        final Result result = e.getResult();
        try {
            final PasswordPolicyResponseControl control =
                    result.getControl(PasswordPolicyResponseControl.DECODER,
                            new DecodeOptions());
            if (!(control == null)) {
                System.out.println("Password policy error "
                        + control.getErrorType().toString() + " for " + dn);
            }
        } catch (final DecodeException de) {
            // Failed to decode the response control.
        }
    } catch (final DecodeException e) {
        // Failed to decode the response control.
    }
}

OpenDJ directory server supports the Password Policy Controls. To obtain the output from the excerpt, you can change the default password policy configuration to set a maximum password age and a warning interval, change Barbara Jensen's password, and then run the example during the warning interval and after the password has expired. See the OpenDJ Administration Guide procedure explaining how To Adjust the Default Password Policy in the Administration Guide for an example of how to adjust the maximum password age. Also set a short password-expiration-warning-interval value.

For a warning:

Password policy warning timeBeforeExpiration, value 237 for
 uid=bjensen,ou=People,dc=example,dc=com

For an error:

Password policy error passwordExpired for
 uid=bjensen,ou=People,dc=example,dc=com

Microsoft defined a Permissive Modify Request Control that relaxes some constraints when your application performs a modify operation and tries to add an attribute that already exists, or to delete an attribute that does not exist.

if (isSupported(PermissiveModifyRequestControl.OID)) {
    final String dn = "uid=bjensen,ou=People,dc=example,dc=com";

    final ModifyRequest request =
            Requests.newModifyRequest(dn)
                .addControl(PermissiveModifyRequestControl.newControl(true))
                .addModification(ModificationType.ADD, "uid", "bjensen");

    connection.modify(request);
    System.out.println("Permissive modify did not complain about "
            + "attempt to add uid: bjensen to " + dn + ".");
}

OpenDJ directory server supports the Permissive Modify Request Control:

Permissive modify did not complain about attempt to add
 uid: bjensen to uid=bjensen,ou=People,dc=example,dc=com.

See Section 10.5, "Entry Change Notification Response Controls".

RFC 4527, LDAP Read Entry Controls, describes the post-read controls that let your application get the content of an entry immediately after modifications are applied.

if (isSupported(PostReadRequestControl.OID)) {
    final String dn = "uid=bjensen,ou=People,dc=example,dc=com";

    final ModifyRequest request =
            Requests.newModifyRequest(dn)
            .addControl(PostReadRequestControl.newControl(true, "description"))
            .addModification(ModificationType.REPLACE,
                    "description", "Using the PostReadRequestControl");

    final Result result = connection.modify(request);
    try {
        final PostReadResponseControl control =
                result.getControl(PostReadResponseControl.DECODER,
                        new DecodeOptions());
        final Entry entry = control.getEntry();

        final LDIFEntryWriter writer = new LDIFEntryWriter(System.out);
        writer.writeEntry(entry);
        writer.close();
    } catch (final DecodeException e) {
        // Failed to decode the response control.
    } catch (final IOException e) {
        // The writer could not write to System.out.
    }
}

OpenDJ directory server supports these controls:

dn: uid=bjensen,ou=People,dc=example,dc=com
description: Using the PostReadRequestControl

RFC 4527, LDAP Read Entry Controls, describes the pre-read controls that let your application get the content of an entry immediately before modifications are applied.

if (isSupported(PreReadRequestControl.OID)) {
    final String dn = "uid=bjensen,ou=People,dc=example,dc=com";

    final ModifyRequest request =
            Requests.newModifyRequest(dn)
            .addControl(PreReadRequestControl.newControl(true, "mail"))
            .addModification(
                    ModificationType.REPLACE, "mail", "modified@example.com");

    final Result result = connection.modify(request);
    try {
        final PreReadResponseControl control =
                result.getControl(PreReadResponseControl.DECODER,
                        new DecodeOptions());
        final Entry entry = control.getEntry();

        final LDIFEntryWriter writer = new LDIFEntryWriter(System.out);
        writer.writeEntry(entry);
        writer.close();
    } catch (final DecodeException e) {
        // Failed to decode the response control.
    } catch (final IOException e) {
        // The writer could not write to System.out.
    }
}

OpenDJ directory server supports these controls:

dn: uid=bjensen,ou=People,dc=example,dc=com
mail: bjensen@example.com

Proxied authorization provides a standard control as defined in RFC 4370 (and an earlier Internet-Draft) for binding with the user credentials of a proxy, who carries out LDAP operations on behalf of other users. You might use proxied authorization, for example, to have your application bind with its credentials, and then carry out operations as the users who login to the application.

if (isSupported(ProxiedAuthV2RequestControl.OID)) {
    final String bindDN = "cn=My App,ou=Apps,dc=example,dc=com";
    final String targetDn = "uid=bjensen,ou=People,dc=example,dc=com";
    final String authzId = "dn:uid=kvaughan,ou=People,dc=example,dc=com";

    final ModifyRequest request =
            Requests.newModifyRequest(targetDn)
            .addControl(ProxiedAuthV2RequestControl.newControl(authzId))
            .addModification(ModificationType.REPLACE, "description",
                    "Done with proxied authz");

    connection.bind(bindDN, "password".toCharArray());
    connection.modify(request);
    final Entry entry = connection.readEntry(targetDn, "description");

    final LDIFEntryWriter writer = new LDIFEntryWriter(System.out);
    try {
        writer.writeEntry(entry);
        writer.close();
    } catch (final IOException e) {
        // The writer could not write to System.out.
    }
}

OpenDJ supports proxied authorization, and the example works with the sample data:

dn: uid=bjensen,ou=People,dc=example,dc=com
description: Done with proxied authz

The server-side sort controls are described in RFC 2891, LDAP Control Extension for Server Side Sorting of Search Results. If possible, sort on the client side instead to reduce load on the server. If not, then you can request a server-side sort.

static void useServerSideSortRequestControl(Connection connection)
        throws ErrorResultException {
    if (isSupported(ServerSideSortRequestControl.OID)) {
        final SearchRequest request =
                Requests.newSearchRequest("ou=People,dc=example,dc=com",
                        SearchScope.WHOLE_SUBTREE, "(sn=Jensen)", "cn")
                        .addControl(ServerSideSortRequestControl.newControl(
                                        true, new SortKey("cn")));

        final SearchResultHandler resultHandler = new MySearchResultHandler();
        final Result result = connection.search(request, resultHandler);

        try {
            final ServerSideSortResponseControl control =
                    result.getControl(ServerSideSortResponseControl.DECODER,
                            new DecodeOptions());
            if (control != null && control.getResult() == ResultCode.SUCCESS) {
                System.out.println("# Entries are sorted.");
            } else {
                System.out.println("# Entries not necessarily sorted");
            }
        } catch (final DecodeException e) {
            // Failed to decode the response control.
        }
    } else {
        System.out.println("ServerSideSortRequestControl not supported");
    }
}

private static class MySearchResultHandler implements SearchResultHandler {

    @Override
    public void handleErrorResult(ErrorResultException error) {
        // Ignore.
    }

    @Override
    public void handleResult(Result result) {
        // Ignore.
    }

    @Override
    public boolean handleEntry(SearchResultEntry entry) {
        final LDIFEntryWriter writer = new LDIFEntryWriter(System.out);
        try {
            writer.writeEntry(entry);
            writer.flush();
        } catch (final IOException e) {
            // The writer could not write to System.out.
        }
        return true;
    }

    @Override
    public boolean handleReference(SearchResultReference reference) {
        System.out.println("Got a reference: " + reference.toString());
        return false;
    }
}

OpenDJ directory server supports server-side sorting:

dn: uid=ajensen,ou=People,dc=example,dc=com
cn: Allison Jensen

dn: uid=bjensen,ou=People,dc=example,dc=com
cn: Barbara Jensen
cn: Babs Jensen

dn: uid=bjense2,ou=People,dc=example,dc=com
cn: Bjorn Jensen

dn: uid=gjensen,ou=People,dc=example,dc=com
cn: Gern Jensen

dn: uid=jjensen,ou=People,dc=example,dc=com
cn: Jody Jensen

dn: uid=kjensen,ou=People,dc=example,dc=com
cn: Kurt Jensen

dn: uid=rjense2,ou=People,dc=example,dc=com
cn: Randy Jensen

dn: uid=rjensen,ou=People,dc=example,dc=com
cn: Richard Jensen

dn: uid=tjensen,ou=People,dc=example,dc=com
cn: Ted Jensen

# Entries are sorted.

RFC 2696, LDAP Control Extension for Simple Paged Results Manipulation, defines a control for simple paging of search results that works with a cookie mechanism.

if (isSupported(SimplePagedResultsControl.OID)) {
    ByteString cookie = ByteString.empty();
    SearchRequest request;
    final SearchResultHandler resultHandler = new MySearchResultHandler();
    Result result;

    int page = 1;
    do {
        System.out.println("# Simple paged results: Page " + page);

        request =
                Requests.newSearchRequest("dc=example,dc=com",
                        SearchScope.WHOLE_SUBTREE, "(sn=Jensen)", "cn")
                        .addControl(SimplePagedResultsControl.newControl(
                                true, 3, cookie));

        result = connection.search(request, resultHandler);
        try {
            SimplePagedResultsControl control =
                    result.getControl(SimplePagedResultsControl.DECODER,
                            new DecodeOptions());
            cookie = control.getCookie();
        } catch (final DecodeException e) {
            // Failed to decode the response control.
        }

        ++page;
    } while (cookie.length() != 0);
}

OpenDJ directory server supports getting simple paged results:

# Simple paged results: Page 1
dn: uid=ajensen,ou=People,dc=example,dc=com
cn: Allison Jensen

dn: uid=bjense2,ou=People,dc=example,dc=com
cn: Bjorn Jensen

dn: uid=bjensen,ou=People,dc=example,dc=com
cn: Barbara Jensen
cn: Babs Jensen

# Simple paged results: Page 2
dn: uid=gjensen,ou=People,dc=example,dc=com
cn: Gern Jensen

dn: uid=jjensen,ou=People,dc=example,dc=com
cn: Jody Jensen

dn: uid=kjensen,ou=People,dc=example,dc=com
cn: Kurt Jensen

# Simple paged results: Page 3
dn: uid=rjense2,ou=People,dc=example,dc=com
cn: Randy Jensen

dn: uid=rjensen,ou=People,dc=example,dc=com
cn: Richard Jensen

dn: uid=tjensen,ou=People,dc=example,dc=com
cn: Ted Jensen

RFC 3672, Subentries in LDAP, describes subentries and also the subentries request control. When you perform a search without the control and visibility set to TRUE, subentries are only visible in searches with SearchScope.BASE_OBJECT.

if (isSupported(SubentriesRequestControl.OID)) {
    final SearchRequest request =
            Requests.newSearchRequest("dc=example,dc=com",
                        SearchScope.WHOLE_SUBTREE,
                        "cn=*Class of Service", "cn", "subtreeSpecification")
                    .addControl(SubentriesRequestControl.newControl(
                        true, true));

    final ConnectionEntryReader reader = connection.search(request);
    final LDIFEntryWriter writer = new LDIFEntryWriter(System.out);
    try {
        while (reader.hasNext()) {
            if (reader.isEntry()) {
                final SearchResultEntry entry = reader.readEntry();
                writer.writeEntry(entry);
            }
        }
        writer.close();
    } catch (final ErrorResultIOException e) {
        // Request failed due to an IO problem.
    } catch (final SearchResultReferenceIOException e) {
        // Read a reference, rather than an entry.
    } catch (final IOException e) {
        // The writer could not write to System.out.
    }
}

OpenDJ directory server supports the control.

dn: cn=Bronze Class of Service,dc=example,dc=com
cn: Bronze Class of Service
subtreeSpecification: { base "ou=People", specificationFilter "(classOfService=
 bronze)" }

dn: cn=Silver Class of Service,dc=example,dc=com
cn: Silver Class of Service
subtreeSpecification: { base "ou=People", specificationFilter "(classOfService=
 silver)" }

dn: cn=Gold Class of Service,dc=example,dc=com
cn: Gold Class of Service
subtreeSpecification: { base "ou=People", specificationFilter "(classOfService=
 gold)" }

The subtree delete request control, described in the Internet-Draft Tree Delete Control, lets your application delete an entire branch of entries starting with the entry you target for deletion.

if (isSupported(SubtreeDeleteRequestControl.OID)) {

    final String dn = "ou=Apps,dc=example,dc=com";
    final DeleteRequest request =
            Requests.newDeleteRequest(dn)
                    .addControl(SubtreeDeleteRequestControl.newControl(true));

    final Result result = connection.delete(request);
    if (result.isSuccess()) {
        System.out.println("Successfully deleted " + dn
                + " and all entries below.");
    } else {
        System.out.println("Result: " + result.getDiagnosticMessage());
    }
}

OpenDJ directory server supports the subtree delete control:

Successfully deleted ou=Apps,dc=example,dc=com and all entries below.

The virtual list view controls are intended to be used by applications that let users browse lists of directory entries. The Internet-Draft LDAP Extensions for Scrolling View Browsing of Search Results describes the controls. The virtual list view request control is used in conjunction with the server-side sort control such that the subset of entries the directory server returns from a search are a window into the full sorted list.

if (isSupported(VirtualListViewRequestControl.OID)) {
    ByteString contextID = ByteString.empty();

    // Add a window of 2 entries on either side of the first sn=Jensen entry.
    final SearchRequest request =
            Requests.newSearchRequest("ou=People,dc=example,dc=com",
                    SearchScope.WHOLE_SUBTREE, "(sn=*)", "sn", "givenName")
                    .addControl(ServerSideSortRequestControl.newControl(
                            true, new SortKey("sn")))
                    .addControl(
                            VirtualListViewRequestControl.newAssertionControl(
                                    true,
                                    ByteString.valueOf("Jensen"),
                                    2, 2, contextID));

    final SearchResultHandler resultHandler = new MySearchResultHandler();
    final Result result = connection.search(request, resultHandler);

    try {
        final ServerSideSortResponseControl sssControl =
                result.getControl(ServerSideSortResponseControl.DECODER,
                        new DecodeOptions());
        if (sssControl != null && sssControl.getResult() == ResultCode.SUCCESS){
            System.out.println("# Entries are sorted.");
        } else {
            System.out.println("# Entries not necessarily sorted");
        }

        final VirtualListViewResponseControl vlvControl =
                result.getControl(VirtualListViewResponseControl.DECODER,
                        new DecodeOptions());
        System.out.println("# Position in list: "
                + vlvControl.getTargetPosition() + "/"
                + vlvControl.getContentCount());
    } catch (final DecodeException e) {
        // Failed to decode the response control.
    }
}

OpenDJ directory server supports the virtual list view controls. In order to set up OpenDJ directory server to produce the following output with the example code, use OpenDJ Control Panel > Manage Indexes > New VLV Index... to set up a virtual list view index for people by last name, using the filter (|(givenName=*)(sn=*)), and sorting first by surname, sn, in ascending order, then by given name also in ascending order.

dn: uid=skellehe,ou=People,dc=example,dc=com
givenName: Sue
sn: Kelleher

dn: uid=ejohnson,ou=People,dc=example,dc=com
givenName: Emanuel
sn: Johnson

dn: uid=ajensen,ou=People,dc=example,dc=com
givenName: Allison
sn: Jensen

dn: uid=bjense2,ou=People,dc=example,dc=com
givenName: Bjorn
sn: Jensen

dn: uid=bjensen,ou=People,dc=example,dc=com
givenName: Barbara
sn: Jensen

# Entries are sorted.
# Position in list: 92/150

OpenDJ LDAP SDK supports many controls, but you might still need to work with additional controls. If so, then in some cases you can use the GenericControl class when adding the control to your request.

For example, the Microsoft LDAP Server Notification Control with OID 1.2.840.113556.1.4.528 can be used to register a change notification request for a search on Microsoft Active Directory. You can use a GenericControl.newControl() static method to add the request control to your search.

        final SearchScope scope = SearchScope.WHOLE_SUBTREE;
        final String filter = "(objectclass=*)";
        final String[] attributes = {
            "objectclass", "objectGUID", "isDeleted", "uSNChanged"
        };

        // Create an LDIF writer which will write the search results to stdout.
        final LDIFEntryWriter writer = new LDIFEntryWriter(System.out);

        // Connect and bind to the server.
        final LDAPConnectionFactory factory =
                new LDAPConnectionFactory(hostName, port);
        Connection connection = null;

        try {
            connection = factory.getConnection();
            connection.bind(userName, password.toCharArray());

            // Read the entries and output them as LDIF.
            final SearchRequest request =
                    Requests
                            .newSearchRequest(baseDN, scope, filter, attributes)
                            .addControl(
                                    GenericControl
                                            .newControl(
                                                    "1.2.840.113556.1.4.528",
                                                    true));
            final ConnectionEntryReader reader = connection.search(request);
            while (reader.hasNext()) {
                if (!reader.isReference()) {
                    final SearchResultEntry entry = reader.readEntry();
                    writer.writeComment("Search result entry: "
                            + entry.getName().toString());
                    writer.writeEntry(entry);
                    writer.flush();
                } else {
                    final SearchResultReference ref = reader.readReference();

                    // Got a continuation reference.
                    writer.writeComment("Search result reference: "
                            + ref.getURIs().toString());
                }
            }
        } 

When you run the search against Active Directory and then create, update, and delete a new user, in this example CN=New User,CN=Users,DC=ad,DC=example,DC=com, Active Directory notifies you of changes to directory data.

# Search result entry: CN=RID Set,CN=WIN2008R2641,OU=Domain Controllers,
 DC=ad,DC=example,DC=com
dn: CN=RID Set,CN=WIN2008R2641,OU=Domain Controllers,DC=ad,DC=example,DC=com
objectClass: top
objectClass: rIDSet
objectGUID:: 178zQQic3EOoBOB1j2QVgQ==
uSNChanged: 12446

# Search result entry: CN=New User,CN=Users,DC=ad,DC=example,DC=com
dn: CN=New User,CN=Users,DC=ad,DC=example,DC=com
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: user
objectGUID:: 7XE/OoJdFEqAegwAi2eNlA==
uSNChanged: 12753

# Search result entry: CN=New User,CN=Users,DC=ad,DC=example,DC=com
dn: CN=New User,CN=Users,DC=ad,DC=example,DC=com
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: user
objectGUID:: 7XE/OoJdFEqAegwAi2eNlA==
uSNChanged: 12755

# Search result entry: CN=New User,CN=Users,DC=ad,DC=example,DC=com
dn: CN=New User,CN=Users,DC=ad,DC=example,DC=com
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: user
objectGUID:: 7XE/OoJdFEqAegwAi2eNlA==
uSNChanged: 12757

# Search result entry: CN=New User,CN=Users,DC=ad,DC=example,DC=com
dn: CN=New User,CN=Users,DC=ad,DC=example,DC=com
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: user
objectGUID:: 7XE/OoJdFEqAegwAi2eNlA==
uSNChanged: 12758

# Search result entry: CN=New User\0ADEL:3a3f71ed-5d82-4a14-807a-0c008b678d94,
# CN=Deleted Objects,DC=ad,DC=example,DC=com
dn: CN=New User\0ADEL:3a3f71ed-5d82-4a14-807a-0c008b678d94,CN=Deleted Objects,
 DC=ad,DC=example,DC=com
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: user
objectGUID:: 7XE/OoJdFEqAegwAi2eNlA==
isDeleted: TRUE
uSNChanged: 12759

The GenericControl class is useful with controls that do not require you to encode complex request values, or decode complex response values. If the control you want to you requires complex encoding or decoding, you might have to implement org.forgerock.opendj.ldap.controls.Control.

Extended operations allow additional operations to be defined for services not already available in the protocol

For OpenDJ, the extended operations supported are listed in the Administration Guide appendix, LDAP Extended Operations in the Administration Guide. You can access the list of OIDs for supported LDAP controls by reading the supportedExtension attribute of the root DSE.

$ ldapsearch
 --baseDN ""
 --searchScope base
 --port 1389
 "(objectclass=*)" supportedExtension
dn: 
supportedExtension: 1.3.6.1.1.8
supportedExtension: 1.3.6.1.4.1.26027.1.6.1
supportedExtension: 1.3.6.1.4.1.26027.1.6.2
supportedExtension: 1.3.6.1.4.1.26027.1.6.3
supportedExtension: 1.3.6.1.4.1.4203.1.11.1
supportedExtension: 1.3.6.1.4.1.4203.1.11.3
supportedExtension: 1.3.6.1.4.1.1466.20037

The following excerpt shows code to check for supported extended operations.

/**
 * Controls supported by the LDAP server.
 */
private static Collection<String> extendedOperations;

/**
 * Populate the list of supported LDAP extended operation OIDs.
 * 
 * @param connection
 *            Active connection to the LDAP server.
 * @throws ErrorResultException
 *             Failed to get list of extended operations.
 */
static void checkSupportedExtendedOperations(Connection connection)
        throws ErrorResultException {
    extendedOperations = RootDSE.readRootDSE(connection)
            .getSupportedExtendedOperations();
}

/**
 * Check whether an extended operation is supported. Call
 * {@code checkSupportedExtendedOperations} first.
 * 
 * @param extendedOperation
 *            Check support for this extended operation, provided by OID.
 * @return True if the control is supported.
 */
static boolean isSupported(final String extendedOperation) {
    if (extendedOperations != null && !extendedOperations.isEmpty()) {
        return extendedOperations.contains(extendedOperation);
    }
    return false;
}

RFC 3909, LDAP Cancel Operation, defines an extended operation that lets you cancel an operation in progress and get an indication of the outcome.

The Cancel extended request uses the request ID of operation you want to cancel, and so therefore works with asynchronous searches and updates. Depending on the delay between your application sending the Cancel request and the directory server receiving the request, the server might have already finished processing the original request before it receives your Cancel request.

You can add a Cancel extended request for example to stop handling entries returned from a search if the directory server returns more entries than you want.

private static final CountDownLatch COMPLETION_LATCH = new CountDownLatch(1);
private static final CountDownLatch CANCEL_LATCH = new CountDownLatch(1);
private static final LDIFEntryWriter WRITER = new LDIFEntryWriter(System.out);

static int requestID;
static int entryCount = 0;

// The requestID is obtained from the future result of the asynchronous search.
// For more context see the example, SearchAsync.java.

private static final class SearchResultHandlerImpl
        implements SearchResultHandler {

    @Override
    public synchronized boolean handleEntry(final SearchResultEntry entry) {
        try {
            // Cancel the search if it returns too many results.
            if (entryCount < 10) {
                WRITER.writeComment("Search result entry: "
                        + entry.getName().toString());
                WRITER.writeEntry(entry);
                ++entryCount;
            } else {
                CancelExtendedRequest request =
                        Requests.newCancelExtendedRequest(requestID);
                connection.extendedRequestAsync(
                        request, null, new CancelResultHandlerImpl());
                return false;
            }
        } catch (final IOException e) {
            System.err.println(e.getMessage());
            resultCode = ResultCode.CLIENT_SIDE_LOCAL_ERROR.intValue();
            COMPLETION_LATCH.countDown();
            return false;
        }
        return true;
    }
    ...
}

private static final class CancelResultHandlerImpl
        implements ResultHandler<ExtendedResult> {

    @Override
    public void handleErrorResult(final ErrorResultException error) {
        System.err.println("Cancel request failed with result code: "
                + error.getResult().getResultCode().intValue());
        CANCEL_LATCH.countDown();
    }

    @Override
    public void handleResult(final ExtendedResult result) {
        System.err.println("Cancel request succeeded");
        CANCEL_LATCH.countDown();
    }

}

OpenDJ directory server supports the cancel operation. If OpenDJ directory server manages to return all entries in Example.ldif before it receives the Cancel extended request, you can see the Cancel request fail because the request ID refers to the search, which is no longer in progress. Try adding a new base DN using OpenDJ control panel and adding the default 2000 generated entries to ensure more search results. For example if dc=example,dc=org contains 2000 generated entries, and the SearchAsync example is run with the arguments sub objectclass=* cn for scope, filter, and attributes respectively, then the example produces something like the following output:

Canceled: Processing on this operation was terminated as a result of receiving
 a cancel request (message ID 3)
# Search result entry: dc=example,dc=org
dn: dc=example,dc=org

# Search result entry: ou=People,dc=example,dc=org
dn: ou=People,dc=example,dc=org

# Search result entry: uid=user.0,ou=People,dc=example,dc=org
dn: uid=user.0,ou=People,dc=example,dc=org
cn: Aaccf Amar

...

Cancel request succeeded

RFC 3062, LDAP Password Modify Extended Operation, defines an extended operation for modifying user passwords that does not depend on the authentication identity, nor on the way passwords are stored.

if (isSupported(PasswordModifyExtendedRequest.OID)) {
    final String userIdentity = "u:scarter";
    final char[] oldPassword = "sprain".toCharArray();
    final char[] newPassword = "secret12".toCharArray();

    final PasswordModifyExtendedRequest request =
            Requests.newPasswordModifyExtendedRequest()
                .setUserIdentity(userIdentity)
                .setOldPassword(oldPassword)
                .setNewPassword(newPassword);

    final PasswordModifyExtendedResult result =
            connection.extendedRequest(request);
    if (result.isSuccess()) {
        System.out.println("Changed password for " + userIdentity);
    } else {
        System.err.println(result.getDiagnosticMessage());
    }
}

OpenDJ directory server supports the password modify operation.

Changed password for u:scarter

Use Start TLS when setting up your connection to protect what your application sends to and receives from the directory server. For an example, read the section on Start TLS & SSL Authentication.

RFC 4532, LDAP "Who am I?" Operation, defines an extended operation that lets your application determine the current authorization ID.

if (isSupported(WhoAmIExtendedRequest.OID)) {

    final String name = "uid=bjensen,ou=People,dc=example,dc=com";
    final char[] password = "hifalutin".toCharArray();

    final Result result = connection.bind(name, password);
    if (result.isSuccess()) {

        final WhoAmIExtendedRequest request =
                Requests.newWhoAmIExtendedRequest();
        final WhoAmIExtendedResult extResult =
                connection.extendedRequest(request);

        if (extResult.isSuccess()) {
            System.out.println("Authz ID: "  + extResult.getAuthorizationID());
        }
    }
}

OpenDJ directory server supports the "Who am I?" operation.

Authz ID: dn:uid=bjensen,ou=People,dc=example,dc=com

As shown in the Proxy example, the Connections.newFixedConnectionPool() returns a connection pool of the maximum size you specify.

final List<ConnectionFactory> factories = new LinkedList<~>();

factories.add(Connections.newFixedConnectionPool(Connections
        .newAuthenticatedConnectionFactory(Connections
                .newHeartBeatConnectionFactory(new LDAPConnectionFactory(
                        remoteAddress, remotePort)),
                        Requests.newSimpleBindRequest(proxyDN,
                                proxyPassword.toCharArray())),
                                Integer.MAX_VALUE));

Connections are returned to the pool when you close() them. Notice that Connections also provides methods to return ConnectionFactorys with a heart beat check on connections provided by the factory, and connection factories that authenticate connections before returning them.

Connections in the pool are intended for reuse. The Proxy gets an authenticated connection, which is a connection where the OpenDJ LDAP SDK passes a bind request immediately when getting the connection. The Proxy then uses proxied authorization to handle the identity from the client requesting the operation. As a rule, either handle binds separately and use proxied authorization as in the Proxy example, or else make sure that the first operation on a connection retrieved from the pool is a bind that correctly authenticates the user currently served by the connection.

When you close() a connection from the pool, the OpenDJ LDAP SDK does not perform an unbind(). This is why you must be careful about how you manage authentication on connections from a pool.

The Connections.newLoadBalancer() method returns a load balancer based on the algorithm you choose. Algorithms include both round robin for equitably sharing load across local directory servers, and also failover usually used for switching automatically from an unresponsive server group to an alternative server group. The algorithms take collections of connection factories, such as those that you set up for connection pooling.

The following excerpt shows how to set up round robin load balancing across directory servers.

final List<ConnectionFactory> factories = new LinkedList<ConnectionFactory>();

// Set up a ConnectionFactory for each directory server in the pool as shown in
// the previous example, and then set up a load balancer.

final RoundRobinLoadBalancingAlgorithm algorithm =
        new RoundRobinLoadBalancingAlgorithm(factories);

final ConnectionFactory factory = Connections.newLoadBalancer(algorithm);

With multiple pools of directory servers, for example in a deployment across multiple data centers, also use fail over load balancing. Fail over load balancing directs all requests to the first (preferred) pool of servers until problems are encountered with the connections to that pool. Then it fails over to the next pool in the list. Therefore in each data center you can set up round robin load balancing, and then set up fail over load balancing across data centers.

// localFactory:  ConnectionFactory to servers in the local data center
// remoteFactory: ConnectionFactory for servers in a remote data center
// localFactory and remoteFactory use round robin load balancing "internally".

final List<ConnectionFactory> factories =
        Arrays.asList(localFactory, remoteFactory);

final FailoverLoadBalancingAlgorithm algorithm =
        new FailoverLoadBalancingAlgorithm(factories);

final ConnectionFactory factory = Connections.newLoadBalancer(algorithm);

The algorithms also include constructors that let you adjust timeouts and so forth.

You create an LDAPListener to handle incoming client connections. The LDAPListener takes a connection handler that deals with the connections, in this case connections back to the directory servers handling client requests.

final LDAPListenerOptions options = new LDAPListenerOptions().setBacklog(4096);
LDAPListener listener = null;
try {
    listener = new LDAPListener(localAddress, localPort, connectionHandler,
            options);
    System.out.println("Press any key to stop the server...");
    System.in.read();
} catch (final IOException e) {
    System.out.println("Error listening on " + localAddress + ":" + localPort);
    e.printStackTrace();
} finally {
    if (listener != null) {
        listener.close();
    }
}

You get a ServerConnectionFactory to handle requests coming from clients. The ServerConnectionFactory takes a request handler that deals with the incoming client requests. The request handler implements handlers for all supported operations. The Proxy example implements a ProxyBackend to handle requests. The ProxyBackend sends the requests on to the backend directory servers and routes the results returned back to client applications.

final ProxyBackend backend = new ProxyBackend(factory, bindFactory);
final ServerConnectionFactory<LDAPClientContext, Integer> connectionHandler =
        Connections.newServerConnectionFactory(backend);

See the Proxy example code for details about the ProxyBackend implementation.

Suppose you have a client application that expects a different attribute name, such as fullname for a standard attribute like cn (common name), and that expects a distinguished name (DN) suffix different from what is stored in the directory. If you cannot change the application, one possible alternative is a proxy layer that does DN and attribute rewriting.^[9]

# A search accessing the directory server
$ ldapsearch -b dc=example,dc=com -p 1389 "(cn=Babs Jensen)" cn
dn: uid=bjensen,ou=People,dc=example,dc=com
cn: Barbara Jensen
cn: Babs Jensen

# The same search search accessing a proxy that rewrites requests and responses
$ ldapsearch -b o=example -p 8389 "(fullname=Babs Jensen)" fullname
dn: uid=bjensen,ou=People,o=example
fullname: Barbara Jensen
fullname: Babs Jensen

In the above output, the rewriter proxy listens on port 8389, connecting to a directory server listening on 1389. The directory server contains data from Example.ldif.