LDAP Configuration documentation for the dotCMS Content Management System

To configure dotCMS to integrate with LDAP you should use a ROOT folder plugin to overwrite the portal.properties file (/dotserver/tomcat-8.0.18/webapps/ROOT/WEB-INF/classes/portal.properties). The following configuration will work with any LDAP v3 directory server (Active Directory, eDirectory, or Sun Directory Server).

Note: LDAP and Active Directory Support are only included with dotCMS Enterprise Editions.

How It Works

LDAP works as a pre-hook to authentication. Every time a user logs in it will query the LDAP server and sync the user information and group information to dotCMS. Then dotCMS will authenticate and authorize the user. The recommended way to integrate into LDAP is to create dotCMS roles with a Role Key that matches groups created in LDAP. Make sure that the group attribute on the user returns these users (see configuration below). As noted below you can use a regular expression and strip to organize these groups.


  • Roles are stored hierarchically.
  • LDAP maps to Role Keys.
    • So your LDAP Group name must map to a dotCMS Role Key.
  • Role Keys need to map exactly to the LDAP Group, and are case sensitive.
  • The Role Keys for pre-defined System Roles are the name of the Role. e.g. the Role Key for the “CMS Owner” user is “CMS Owner”.
  • Make sure at least one of the Roles a user will get assigned have Tabs assigned to them in the Role Manager (so that when the user logs in he/she will see something in the backend of dotCMS).


The following configuration properties must be set properly to configure LDAP in dotCMS.

#Base Config

#Set SSL if you are using LDAPS  or leave blank

#Note: Set path to keystore with root server cert imported or leave blank 

#Note this should be full dn of user

#Note The filter will allow you to only pull groups which match teh following regular expression
#If you are not using the the filter/strip model then set this to

#Note Prefix dotCMS should strip from group name.  Leave blank to not strip any prefix.
#So if your group in LDAP was dotcms_CMS_Administrators the actual dotCMS group would be just CMS_Administrator

#If you set to false any user created from LDAP will not be able to log into dotCMS if LDAP is not availible. 

Matching dotCMS User Properties to LDAP Attributes

The auth.impl.ldap.attrib.* properties determine how dotCMS User information is matched to LDAP attributes. Each property specifies a dotCMS User property, and is set to the LDAP attribute the User property will be mapped to. Any attribute that is left blank will not be synchronized from LDAP.


Note: For a dotCMS user to be authenticated via LDAP, the user account must have valid values in the first name, last name, and email address fields. User accounts which are automatically created through LDAP authentication will automatically have these fields created and populated, but if you manually create any user accounts which will be authenticated via LDAP, you must make sure to fill in these fields.

Front End LDAP Authenticated Login

To allow users to login to the front end via LDAP, make sure the following property is set in the dotmarketing-config.properties file (via plugin), and matches the value of your auth.pipeline.pre setting to force front end logins to authenticate via LDAP.

#Front end LDAP login


If you encounter problems when using LDAP with ActiveDirectory, please make sure to read the Active Directory Error Codes documentation for help in troubleshooting Active Directory authentication issues.

In addition, the following are some common problems you may encounter while setting up your LDAP configuration, with some suggestions for troubleshooting and correcting the problems.

Failures to connect with LDAP

To test the LDAP connection:

  1. Download jxplorer.
  2. Try to connect to your LDAP directory with the same settings as your dotCMS LDAP configuration.

If you cannot connect with jxplorer, there is a problem with your LDAP configuration parameters. Correct the parameters, and after you've successfully connected with jxplorer, re-try the dotCMS LDAP connection.

Incorrect setup of the LDAP memberOf attribute

To view the value of the memberOf attribute:

  1. Connect to LDAP with jxplorer.
  2. Search for the user using the userId LDAP attribute configured.
  3. Inspect the memberOf attribute to see what groups it exposes on the actual user.
    • Important: the Role Keys need to EXACTLY match the results of the memberOf attribute (see Notes, above).

If necessary, modify the configuration to ensure the memberOf attribute provides proper group exposure.

Existence of a user named LDAP User within LDAP

The LDAP User account must only exist in dotCMS. If you have a user account named LDAP User in your LDAP configuration outside of dotCMS, your LDAP connection will fail.

If you have verified your connection and memberOf attribute, but still are unable to authenticate dotCMS users with LDAP, verify that you do not have an LDAP User in your LDAP configuration. If you have an LDAP User in your LDAP configuration, you must change the name of the user in your LDAP configuration to be able to use LDAP with dotCMS.