Submit Feedback

Connecting to an LDAP Directory

Lightweight Directory Access Protocol (LDAP) servers are common user stores for Liferay DXP. You can configure LDAP at the system scope in System Settings or at the instance scope in Instance settings. Users can be imported from or exported to 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 → and click Servers
Click Add to add an LDAP server connection.
Enter configuration values for your LDAP server. See the configuration reference for details.

Note

The configuration represents “best guesses” as to correct defaults, so you must configure your LDAP server with the necessary values. The default attribute mappings usually provide enough data to synchronize back to the Liferay database when a user attempts to log in. To test the connection to your LDAP server, click the Test LDAP Connection button.

If you have more than one LDAP server, you can arrange the servers by order of preference using the up/down arrows. Regardless of how many LDAP servers you add, each server has the same configuration options.

Using the System Settings Scope

Alternatively, you can define an LDAP server connection at the System Settings scope through the System Settings menu or with the usage of OSGi .config files.

Tip

The LDAP server configuration screen in Instance Settings has utilities to assist with configuring an LDAP connection. You can use this utility to validate your settings first, before entering them at the System Settings scope.

The easiest way to do use .config files is to use the GUI and export the configuration. Then you can use the resulting .config file anywhere you need it (such as other nodes in a cluster).

Note

To use config files for LDAP server configuration, you must specify the Virtual Instance ID (in the source, the variable name is companyId) in the exported configuration file, because servers are defined at the instance scope, not the system scope. To do this, specify the virtual instance ID somewhere in the file like this:

companyId=1234

You can find your Virtual Instance ID in Control Panel → Configuration → Virtual Instances.

Checkpoint

Before fine tuning Liferay’s LDAP connections, ensure you’ve taken the following steps:

The LDAP connection is enabled. Depending on your needs, LDAP authentication may be required so that only users who have been bound may log in.
Export/Import: for users in a clustered environment, Enable Import/Export on Startup should be disabled so that there are no massive imports on every node upon start up.
When adding the LDAP server, the Server Name, Default Values, Connection values are correct. It is always a good idea to click the Test LDAP Connection before saving.

Using SSL to Connect to an LDAP Server

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

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

Click Start → Administrative Tools → Certificate Authority.
Highlight the machine that is the certificate authority, right-click on it, and click Properties.
From the General menu, click View Certificate.
Select the Details view, and click Copy To File. Use the resulting wizard to save the certificate as a file.

Import the certificate into the cacerts keystore like this:

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.

Go back to the LDAP 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 like this:
```
ldaps://myLdapServerHostname:636
```