LDAP Configuration Reference

Access LDAP configuration settings from the Global Menu ():

• Control Panel → Configuration → Instance Settings → Security → LDAP
• Control Panel → Configuration → System Settings → Security → LDAP

The LDAP configuration includes the following sections: General, Servers, Connection, Export, and Import.

General

Field	Description
Enabled	Activates LDAP authentication.
Required	Requires users to authenticate through LDAP. When unchecked, users can log in using Liferay credentials.
Use LDAP Password Policy	Uses the LDAP server’s password policy.
Method	Defines the authentication method (Bind or Password Compare).
Password Encryption Algorithm	Defines the encryption algorithm used with Password Compare.

Note

Liferay applies its own password policy to users who have never authenticated through LDAP when the following conditions are met:

• Enabled is checked
• Required is unchecked
• Use LDAP Password Policy is checked

Servers

Click Add to add an LDAP server.

Once you’ve finished configuring LDAP, click Save.

Tip

Use the test options to validate your configuration. Test LDAP Connection checks connectivity and credentials, while Test LDAP Users and Test LDAP Groups verify user and group search filters.

Basic Settings

Field	Description	Example
Server Name	Identifies the LDAP server.	ApacheDS, ActiveDirectory
Clock Skew	Defines the allowed time difference (in milliseconds) between Liferay and the LDAP server for validating users’ modified timestamps during import.	3000

Default Values

Loads predefined configuration values for supported directory servers:

• Apache Directory Server
• Fedora Directory Server
• Microsoft Active Directory Server
• Novell eDirectory
• OpenLDAP
• Other Directory Server

Connection

Field	Description	Example
Base Provider URL	Specifies the LDAP server URL.	ldap://localhost:10389 (ApacheDS), ldap://localhost:389 (Active Directory)
Base DN	Defines the base distinguished name used for directory searches.	dc=example,dc=com, dc=localdomain
Principal	Sets the LDAP administrator user.	uid=admin,ou=system (ApacheDS), cn=Directory Manager (Fedora), admin (AD)
Credentials	Sets the password for the LDAP administrator.

Users

Field	Description	Example
Authentication Search Filter	Defines how Liferay identifies a user during login.	(mail=@email_address@) (ApacheDS/OpenLDAP), (&(objectCategory=person)(sAMAccountName=@user_id@)) (AD)
Import Search Filter	Defines which LDAP entries are imported as users.	(objectClass=person), (objectClass=inetOrgPerson)
Ignore User Search Filter for Authentication	Ignores the authentication filter during login validation.

User Mapping

Field	Description
UUID	Maps the unique identifier.
Screen Name	Maps the user’s screen name.
Email Address	Maps the user’s email.
Password	Maps the password attribute.
First Name	Maps the first name.
Middle Name	Maps the middle name.
Last Name	Maps the last name.
Full Name	Maps the full name.
Job Title	Maps the job title.
Status	Maps the user’s status.
Group	Maps group membership.

Custom Mapping

Field	Description	Example
Custom User Mapping	Maps LDAP attributes to custom user fields.	employeeNumber=customField1
Custom Contact Mapping	Maps LDAP attributes to custom contact fields.	department=contactField1

User Ignore Attributes

Field	Description	Example
User Ignore Attributes	Defines Liferay user attributes LDAP does not overwrite.	birthday

Groups

Field	Description	Example
Import Search Filter	Defines which LDAP entries are imported as groups.	(objectClass=groupOfUniqueNames), (objectClass=group) (AD)

Group Mapping

Field	Description	Example
Group Name	Maps the group name.	cn
Description	Maps the group description.	description, sAMAccountName (AD)
User	Maps the membership attribute.	uniqueMember, member (AD)

Export

Field	Description	Example
Users DN	Defines where users are stored in LDAP.	dc=example,dc=com
User Default Object Classes	Defines object classes for exported users.	top,person,inetOrgPerson,organizationalPerson
Groups DN	Defines where groups are stored in LDAP.	dc=example,dc=com
Group Default Object Classes	Defines object classes for exported groups.	top,groupOfUniqueNames

Connection

The Connection settings include error keyword properties used to interpret LDAP server responses. When a user binds to LDAP, the server returns messages describing success or failure. Because these messages vary by server, configure these keywords to match your directory’s error messages so Liferay can recognize them.

General Settings

Field	Description
Factory Initial	Specifies the initial context factory. Default: com.sun.jndi.ldap.LdapCtxFactory.
Referral	Defines how referrals are handled: Follow (automatically follows referrals), Ignore (ignores referrals), or Throw (throws a ReferralException for each referral).
Page Size	Sets the number of results per page for directory servers that support paging. Must be 1000 or less for Microsoft Active Directory.
Range Size	Sets the number of values returned for multi-valued attributes for servers that support range retrieval. The maximum value depends on the directory server.

Connection Properties

Property	Description
com.sun.jndi.ldap.connect.pool	Enables connection pooling when creating LDAP connections.
com.sun.jndi.ldap.connect.timeout	Sets the connection timeout in milliseconds.
com.sun.jndi.ldap.read.timeout	Sets the read timeout in milliseconds for LDAP operations.

Error Handling Keywords

Define keywords used to interpret LDAP error messages. If your directory server returns different messages, update these values to match.

Field	Description	Example
Error Password Expired Keywords	Matches password expiration messages.	expired
Error Password History Keywords	Matches password history messages.	history
Error User Lockout Keywords	Matches account lockout messages.	retry limit

Export

Field	Description
Enable Export	Exports user updates to LDAP.
Enable Group Export	Exports groups to LDAP. Requires Enable Export.

When export is enabled, user updates trigger LDAP exports. Because fields such as lastLoginDate are updated on login, an export can occur each time a user logs in.

To prevent this, set users.update.last.login=false in portal-ext.properties.

Import

Field	Description
Enable Import	Imports users from LDAP. If disabled, users are imported when they log in.
Enable Import on Startup	Runs a full import when the server starts. Disable in clustered environments to avoid repeated imports.
Import Interval	Defines how often imports run.
Import Method	Defines whether to import by User or Group.
Lock Expiration Time	Defines account lock duration (ms).
Import User Sync Strategy	Defines how users are matched (Auth Type or UUID).
Enable User Password on Import	Assigns passwords during import.
Autogenerate User Password on Import	Generates random passwords.
Default User Password	Sets a default password. Used when password generation is disabled.
Enable Group Cache on Import	Caches group data.
Create Role per Group on Import	Creates a role for each LDAP group.

Note

The LDAP authentication process does not depend on the import method. When users authenticate, they are imported as though the User import method had been selected.

Note

When using the Group import method, users who do not belong to any groups are not imported.

LDAP Options Available in System Settings

Most LDAP configuration is done in Instance Settings. System Settings include additional options and define default values for new virtual instances.

Note

Changes in System Settings apply to the current instance. New instances inherit these settings as defaults.

To modify these options, go to Control Panel → Configuration → System Settings, then open the LDAP entries under Security. Additional settings are available in the Servers entry.