Developing Java LDAP Clients
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>
Read the Root DSE
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.bindafter connecting over LDAPS or StartTLS. ConfigureLDAPConnectionFactorywithSSL_CONTEXTand a trust configuration that validates the server certificate and identity. SetSSL_USE_STARTTLStotrueto negotiate TLS on an LDAP listener. SeegetTrustOptions()inSimpleAuth.javafor certificate and hostname verification. -
For SASL PLAIN, use
SASLAuth.javato see how to construct the bind request. Its StartTLS setup usesTrustManagers.trustAll()for local testing. Use the verified TLS setup above when sending credentials from an application. -
Use
Connection.searchto 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 andSearchfor an SDK example that handles entries and continuation references. Follow referrals only to servers your application trusts. UseConnection.compareto 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
SearchAsyncandModifyAsync. SDK methods report LDAP failures throughLdapException, whose result carries the LDAP result code and diagnostic details. -
Use
Requeststo construct add, modify, modify DN, delete, and extended operation requests. SeeModify,UpdateGroup, andExtendedOperations. For request controls, checksupportedControlbefore depending on a control and seeControlsandUseGenericControl. -
For schema discovery, read
subschemaSubentryor use theReadSchemaexample. For files in LDAP Data Interchange Format (LDIF), use theorg.forgerock.opendj.ldifreaders 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, seeProxyandRewriterProxy.