To configure dotCMS to integrate with LDAP you should use a ROOT folder plugin to overwrite the portal.properties file (/dotserver/$TOMCAT_HOME/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).
There are two possible scenarios when connecting to an LDAP server from dotCMS: the customer uses a certificate purchased directly from a known trusted Certificate Authority (CA) or it uses a self-signed certificate.
Using a trusted CA
When the customer uses an “official” certificate from a trusted CA there's nothing to do, dotCMS should trust their LDAP's certificate by default.
Using a non-trusted CA (self-signed)
The idea behind this process is to get dotCMS to trust any certificate generated by the customer's CA. What's needed is to add customer's ROOT CA certificate to JRE's cacerts or use the system approach to a general use cacerts file. Both ways will work, but there's a caveat when using JRE's: the cert store needs to be updated during each JDK upgrade because the cert store will be overwritten. When adding the certificate to the system, the cacerts file from the JRE will be merged with the custom certs at each upgrade which is a better approach going forward. The preferred way to our cloud is to add it to the system.
Add it to the system
Get the ROOT CA cert from the client
Copy it to
update-ca-trust script will be run everytime there's a change on the trusted certificates, it'll merge all the certs listed in
Add it to JRE's cacerts
In case the above method is not available, we can do it manually:
Search where the cacerts file is, usually in
Create a copy of that file and timestamp it
Add the client's ROOT CA cert to the keystore.
keytool -import -alias <clientCA> -file clientCA.cer -keystore cacerts –storepass changeit
The change in trusted certificates is now added
Java KeyStore in Docker
If you are using Docker you must modify the default Java KeyStore file provided in the dotCMS Docker image, see How to Modify the Java Keystore.
Difference between truststore and keystore
truststore In an SSL handshake, the purpose of a truststore is to have a list of trusted CA's (Certificate Authority) in order to verify credentials from the server it's trying to connect to.
keystore The keystore will contain the private key and own identity certificate to present to other parties (server or client).
There's been some confusion and both terms may have been mixed up. We used to configure the
keystore_path in the
portal.properties file, however that attribute should be left blank.
This is the example in our documentation modified for LDAPS:
#Base Config auth.impl.ldap.initial.context.factory=com.sun.jndi.ldap.LdapCtxFactory auth.pipeline.pre=com.dotcms.enterprise.LDAPProxy #Set SSL if you are using LDAPS or leave blank auth.impl.ldap.security.authentication=SSL # This should be left blank auth.impl.ldap.security.keystore.path= auth.impl.ldap.host=192.168.1.34 auth.impl.ldap.port=636 #Note this should be full dn of user auth.impl.ldap.userid=cn=xxxxxx,ou=Users,dc=miami,dc=dotcms,dc=org auth.impl.ldap.password=xxxxxxx auth.impl.ldap.domainlookup=dc=miami,dc=dotcms,dc=org auth.impl.build.groups=true #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 #auth.impl.ldap.build.group.name.filter=^(.+) auth.impl.ldap.build.group.name.filter=^dotcms_(.+) #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 auth.impl.ldap.build.group.name.filter.strip=dotcms_ #If you set to false any user created from LDAP will not be able to log into dotCMS if LDAP is not availible. auth.impl.ldap.syncPassword=false
Matching dotCMS User Properties to LDAP Attributes
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.
auth.impl.ldap.attrib.user=samAccountName auth.impl.ldap.attrib.firstName=givenName auth.impl.ldap.attrib.middleName=middleName auth.impl.ldap.attrib.lastName=sn auth.impl.ldap.attrib.nickName= auth.impl.ldap.attrib.email=mail auth.impl.ldap.attrib.gender= auth.impl.ldap.attrib.group=memberOf
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 LDAP_FRONTEND_AUTH_IMPLEMENTATION=com.dotcms.enterprise.LDAPImpl
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:
- Download jxplorer.
- 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
To view the value of the
- Connect to LDAP with jxplorer.
- Search for the user using the userId LDAP attribute configured.
- Inspect the
memberOfattribute to see what groups it exposes on the actual user.
- Important: the Role Keys need to EXACTLY match the results of the
memberOfattribute (see Notes, above).
- Important: the Role Keys need to EXACTLY match the results of the
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.