Developing Java LDAP Clients

This example uses the OpenDJ LDAP SDK 5.2.0 to check which LDAP versions a server supports.

Add the SDK to a Maven Project

Use Java 11 or later and Maven 3. Save this pom.xml. The opendj-grizzly dependency brings in the opendj-core SDK and provides its LDAP network transport.

<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>ldap-client</artifactId>
  <version>1.0.0</version>
  <properties>
    <maven.compiler.source>11</maven.compiler.source>
    <maven.compiler.target>11</maven.compiler.target>
  </properties>
  <dependencies>
    <dependency>
      <groupId>org.openidentityplatform.opendj</groupId>
      <artifactId>opendj-grizzly</artifactId>
      <version>5.2.0</version>
    </dependency>
  </dependencies>
</project>

Start the evaluation server from Your First Directory. The example reads the root DSE, an entry with public server information, from its LDAP listener on port 1389.

Save this class as src/main/java/ReadCapabilities.java.

import org.forgerock.opendj.ldap.Connection;
import org.forgerock.opendj.ldap.LDAPConnectionFactory;
import org.forgerock.opendj.ldap.RootDSE;

public final class ReadCapabilities {
    public static void main(String[] args) throws Exception {
        try (LDAPConnectionFactory factory = new LDAPConnectionFactory("localhost", 1389);
             Connection connection = factory.getConnection()) {
            RootDSE rootDse = RootDSE.readRootDSE(connection);
            var versions = rootDse.getSupportedLDAPVersions();
            System.out.println("LDAPv3 supported = " + versions.contains(3));
        }
    }
}

Run this command from the Maven project directory.

mvn -q compile exec:java -Dexec.mainClass=ReadCapabilities

The program prints LDAPv3 supported = true. The RootDSE class also exposes naming contexts, supported controls, and extended operations.

Use the SDK in an Application

  • For simple authentication, call Connection.bind after connecting over LDAPS or StartTLS. Configure LDAPConnectionFactory with SSL_CONTEXT and a trust configuration that validates the server certificate and identity. Set SSL_USE_STARTTLS to true to negotiate TLS on an LDAP listener. See getTrustOptions() in SimpleAuth.java for certificate and hostname verification.

  • For SASL PLAIN, use SASLAuth.java to see how to construct the bind request. Its StartTLS setup uses TrustManagers.trustAll() for local testing. Use the verified TLS setup above when sending credentials from an application.

  • Use Connection.search to read multiple entries. Set a specific base DN, scope and filter, and request the attributes you need. See Searching the Directory for equivalent command-line examples and Search for an SDK example that handles entries and continuation references. Follow referrals only to servers your application trusts. Use Connection.compare to compare an attribute value and check the LDAP result code for the outcome.

  • Use a connection factory or a pool for repeated operations. Close connections when finished with them and close the factory at application shutdown. Use separate connections for binds as different users. For concurrent operations, see SearchAsync and ModifyAsync. SDK methods report LDAP failures through LdapException, whose result carries the LDAP result code and diagnostic details.

  • Use Requests to construct add, modify, modify DN, delete, and extended operation requests. See Modify, UpdateGroup, and ExtendedOperations. For request controls, check supportedControl before depending on a control and see Controls and UseGenericControl.

  • For schema discovery, read subschemaSubentry or use the ReadSchema example. For files in LDAP Data Interchange Format (LDIF), use the org.forgerock.opendj.ldif readers and writers. Use an entry reader for entries and a change record reader for LDIF files that describe updates.

  • The SDK uses localized messages. Handle errors by result code and use getLocalizedMessage() for messages presented to users.

  • A proxy can reuse connections and distribute them among servers with Connections. For listener and request handler examples, see Proxy and RewriterProxy.