LDAP Configuration

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.

Starting with version 22.09, LDAP support is a deprecated feature. It is recommended that customers still using LDAP to integrate with dotCMS begin migration to a different Single Sign-On (SSO) solution, such as SAML (through Azure or another Identity Provider).

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.

Overview

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).

Configuration

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 /usr/share/pki/ca-trust-source/anchors/
Run update-ca-trust extract
Restart dotCMS

The update-ca-trust script will be run everytime there's a change on the trusted certificates, it'll merge all the certs listed in /usr/share/pki/ca-trust-source/anchors/.

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 /etc/pki/java/
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

Restart dotCMS
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).

In dotCMS 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.

Example portal-ext.properties

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

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.

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

Troubleshooting

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 `memberOf` attribute

To view the value of the memberOf attribute:

Connect to LDAP with jxplorer.
Search for the user using the userId LDAP attribute configured.
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.