Managing LDAP Settings Using .config Files

This document has been updated and ported to Liferay Learn and is no longer maintained here.

This article documents how to configure LDAP settings using .config files instead of the Control Panel.

There are a great number of changes in Liferay Digital Experience Platform (DXP), and one of them is how LDAP settings are managed using configuration files. Although changes made in the Control Panel will always supersede settings declared in the portal-ext.properties and .cfg|.config files, using configuration files offers two advantages.

First, changes made to the .cfg|.config does not require restarting the server.

The second advantage is that the settings are not saved to the database.

In DXP, LDAP settings are no longer present in portal.properties. Any settings changes for managing LDAP will not be applied if they are stated in the portal-ext.properties file. By comparison, in Portal 6.2 and earlier, one could simply copy all the relevant settings into portal-ext.properties.

Resolution

To manage LDAP settings quickly and efficiently after the initial connections have been made, system administrators can make changes in a .config file. There are four specific .config files that are required. Please note that Liferay DXP uses the new .config format instead of the older .cfg. 

1. com.liferay.portal.security.ldap.authenticator.configuration.LDAPAuthConfiguration-${HASH_VALUE}.config 
2. com.liferay.portal.security.ldap.configuration.LDAPServerConfiguration-${HASH_VALUE}.config 
3. com.liferay.portal.security.ldap.exportimport.configuration.LDAPExportConfiguration-${HASH_VALUE}.config 
4. com.liferay.portal.security.ldap.exportimport.configuration.LDAPImportConfiguration-${HASH_VALUE}.config 

Those are some very long filenames, and once the hash value is added in they get even longer. To generate the hash values, system administrators can do so in the Control Panel. The hash value is not unique to the system and can be used across multiple systems.

Note: Do this at once after the LDAP is successfully connected. That way, there is no need to keep going back to the Control Panel all the time.

Generating the Config Files in DXP 7.0

1. Navigate to Control Panel → System Settings → Foundation
2. Search for LDAP.
3. Enter the values for LDAP Auth, LDAP Servers, and if necessary, LDAP Export and LDAP Import.
4. From the Control Panel → System Settings → Foundation page, use the 3-dot menu to export the settings and save the file. These files now have the hash value along with the file name.
5. Copy these files into ${LIFERAY_HOME}/osgi/modules.

Generating the Config Files in DXP 7.1

1. Navigate to Control Panel → Configuration → System Settings → Security → LDAP
2. Search for LDAP.
3. Enter the values for LDAP Auth, LDAP Servers, and if necessary, LDAP Export and LDAP Import.
4. From the Control Panel → Configuration → System Settings → Security → LDAP page, use the 3-dot menu to export the settings and save the file. These files now have the hash value along with the file name.
5. Copy these files into ${LIFERAY_HOME}/osgi/modules.

GENERATING THE CONFIG FILES IN DXP 7.2

1. Navigate to Control Panel → Configuration → System Settings → Security → LDAP
2. Enter the values for LDAP Auth, LDAP Servers, and if necessary, LDAP Export and LDAP Import and Save.
3. From the Control Panel → Configuration → System Settings → Security → LDAP page, use the 3-dot menu to export the settings and save the file. These files now have the hash value along with the file name.
4. Copy these files into ${LIFERAY_HOME}/osgi/modules.

There is a new feature in Liferay DXP called Revert to Default. Long time users will recognize the fact that once something has been entered into the UI, it will always supersede configuration files. The Revert to Default option is a new feature that resets the current settings to the initial configuration.

Additional Information

A couple things to note:

• The file content can be edited without changing the hash value.
• Changes to the file content are picked up without a restart.

The last note above is the major difference between the old way via portal-ext.properties, and the new way with OSGi. Changes to the files do not require a restart. No longer does a single typo cost several minutes (or more) of time waiting for the system to restart once it has been fixed.