Connecting to an LDAP Directory

Lightweight Directory Access Protocol (LDAP) servers are common user stores for Liferay DXP. Configure LDAP at the system scope in System Settings or at the instance scope in Instance Settings. You can import or export users to/from LDAP.

Adding a New LDAP Server Connection

To access LDAP configuration settings at the Instance level,

Open the Global Menu () and navigate to Control Panel → Instance Settings.
Click LDAP → Servers.
Click Add to add an LDAP server connection.
Enter configuration values for your LDAP server. See the configuration reference for details.

Note

Default values are only a starting point. Update them based on your LDAP server configuration. The default mappings usually provide enough data to synchronize users when they log in. Use the test options to validate your configuration before saving.

If you have more than one LDAP server, arrange them by order of preference using the up/down arrows. Each server uses the same configuration options.

Using the System Settings Scope

Alternatively, define an LDAP server connection at the System Settings scope through the System Settings menu or by using OSGi .config files.

Tip

The LDAP configuration screen in Instance Settings includes test options to validate your configuration before applying it in System Settings.

The easiest way to use .config files is to export the configuration from the UI. You can then reuse the file across environments (for example, in a cluster).

Note

To use .config files for LDAP server configuration, specify the Virtual Instance ID (companyId) in the exported file, since servers are defined at the instance scope. For example, companyId=1234.

Find the Virtual Instance ID in Control Panel → Configuration → Virtual Instances.

Checkpoint

Before configuring LDAP, verify these things:

LDAP is enabled. If required, users must authenticate through LDAP to log in.
In clustered environments, disable Enable Import/Export on Startup to avoid repeated mass imports on each node during startup.
Verify the server configuration values (Server Name, Default Values, and Connection). Use the test options (Test LDAP Connection, Test LDAP Users, and Test LDAP Groups) to validate the configuration before saving.

Using SSL to Connect to an LDAP Server

If your LDAP directory runs in SSL mode to encrypt credential information on the network, perform extra steps to share the encryption key and certificate between systems.

To share the certificate from Microsoft Active Directory on a Windows Server,

Click Start → Administrative Tools → Certificate Authority.
Select the certificate authority machine, right-click it, and click Properties.
From the General menu, click View Certificate.
Open the Details view and click Copy To File. Use the wizard to export the certificate.

Import the certificate into the cacerts keystore:

keytool -import -trustcacerts -keystore /some/path/java-8-jdk/jre/lib/security/cacerts -storepass changeit -noprompt -alias MyRootCA -file /some/path/MyRootCA.cer

The keytool utility ships as part of the Java SDK.

Return to the LDAP configuration page in the Control Panel.
Modify the LDAP URL in the Base DN field to the secure version by changing the protocol to ldaps and the port to 636:
```
ldaps://myLdapServerHostname:636
```

Save the changes. Communication with the LDAP server is now encrypted.

To configure how Liferay matches users during synchronization, see configuring import and export.

Note

Use SCIM instead of LDAP in Liferay SaaS. SCIM is the recommended approach for cloud-based user provisioning.

Technical Standards and Specifications

Liferay DXP prioritizes consistency with published specifications and standards by relying on standardized platform APIs rather than implementing protocol specifications directly. This approach minimizes vendor-specific behavior and supports predictable integration into diverse IT environments.

Liferay’s LDAP integration relies on the javax.naming.ldap package, a Java API that provides a standardized interface for accessing LDAP directories. Liferay uses this API to import and export users, groups, and membership data from LDAP directories.

The javax.naming.ldap package supports LDAPv3 extended operations and controls as defined by the LDAPv3 technical specification. Liferay does not implement LDAP protocol specifications itself; all LDAP protocol behavior is provided by the underlying Java platform and the directory server.

As a result, LDAP feature availability and behavior in Liferay DXP depend on the capabilities of the directory server and the Java runtime environment in use.