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.
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.
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).
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 to636
like this:ldaps://myLdapServerHostname:636
Save the changes. Communication to LDAP is now encrypted.
To tune or configure how Liferay DXP matches users in LDAP for syncing, please see configuring import and export.
Though Liferay is still enhancing its SCIM offering, you should use SCIM instead of LDAP in Liferay SaaS.