Liferay.com

Contact Us

Request a Demo Get Enterprise Pricing Learn More

Wiki

Main | Proposals

Details

LDAP

Tags: using liferay installation deployment setup

Table of Contents [-+]

This page seeks to explain LDAP's use in Liferay.

<!--

Overview

Set up

via GUI

via portal.properties

-->

Connection Settings

    ldap.base.provider.url=ldap://192.168.94.128:19389
    ldap.base.dn=dc=localdomain
    ldap.security.principal=cn=dirman
    ldap.security.credentials=password

Settings Explained

ldap.base.provider.url
- This tells the portal where the LDAP server is located. Make sure that the computer with Liferay can hit the computer with the LDAP server. Check to make sure that the appropriate ports are opened, etc.

ldap.base.dn=dc=localdomain
- this will usually look something like: "dc=companynamehere,dc=com"

ldap.security.principal=cn=dirman & ldap.security.credentials=password ===
- principal = username
- credentials = password

Check Point

To verify that you have the correct settings, try to connect to the LDAP server using an LDAP browser application such as JXplorer.

Connecting to LDAP over SSL

To connect to LDAP over an SSL you must do the following. (Example provided for Microsoft Active Directory on Windows Server 2003)

On the Win2K3 Domain Controller perform the following steps:

   - Open the certificates mmc snapin.
   - Export the Root Certificate Authority certificate located at: Certificates (Local Computer) mmc snapin>Trusted Root Certification Authorities>MyRootCACertificateName 
     (right click this certificate>all tasks>export>select DER encoded binary X.509 .CER)
   - Copy the exported .cer file to the server where your JDK lives under which liferay is ulitmately running.
   - Import the certificate into the cacerts keystore (you may be able to create your own keystore but this example just imports it into the default 
     cacerts keystore provided by the Sun JDK 1.5.x). The import is handled by a command like the following.

/some/path/jdk1.5.0_11/bin/keytool -import -trustcacerts -keystore /some/path/jdk1.5.0_11/jre/lib/security/cacerts -storepass changeit -noprompt

alias MyRootCA -file /some/path/MyRootCA.cer

   - In liferay admin console>users>authentication>ldap specify a URL like the following (note ldaps:// and port 636 instead of ldap:// and 389 for 
     non-ssl connections).

ldaps:myLdapServerHostname:636

  - Save the change. Test it out.

Authentication

The LDAP class that handles the connection and search of LDAP is LDAPAuth. LDAPUtil is used to help grab attributes.

In portal.properties, LDAP is part of the authentication pipeline:

 auth.pipeline.pre=com.liferay.portal.security.auth.LDAPAuth

When using By Screen Name as user authentication method, the following LDAP filter can be used to match the entered login name:

 (cn=@screen_name@)

Where screen_name is replaced by the login name the user entered. (Note: This is known to work with Liferay 4.3, but I couldn't find any official guarantee for it)

Settings / Configuration

    ldap.auth.enabled=true
    ldap.auth.required=true

    ldap.users.dn=ou=People,dc=localdomain
    ldap.groups.dn=ou=Groups,dc=localdomain

    ldap.user.mappings=screenName=cn\npassword=userPassword\nemailAddress=mail\nfirstName=givenName\nlastName=sn\njobTitle=title\ngroup=groupMembership
    ldap.user.impl=com.liferay.portal.security.ldap.LDAPUser

    ldap.group.mappings=groupName=cn\ndescription=description\nuser=uniqueMember

    ldap.import.user.search.filter=(objectClass=inetOrgPerson)
    ldap.import.group.search.filter=(objectClass=groupOfUniqueNames)

    ldap.auth.search.filter=(mail=@email_address@)

Settings Explained

ldap.auth.enabled=true
- Set ldap.auth.enabled = true to enable LDAP Authentication

ldap.auth.required=true
- Setting required = true means that you must successfully bind with the record in the LDAP server before Liferay will allow the user to log in

ldap.users.dn=ou=People,dc=localdomain
- This is where Liferay will look for users (for authentication, import and export)

ldap.groups.dn=ou=Groups,dc=localdomain
- This is where Liferay will look for groups (for import)

ldap.user.mappings
- VERY IMPORTANT!! Your LDAP user fields may be different from LDAP server to LDAP server, however there are 5 REQUIRED fields in order for the user to be recognized by Liferay as a complete user. There *MUST* be a mapping AND corresponding values in LDAP for the following fields:
  - screenName
  - password
  - emailAddress
  - firstName
  - lastName

ldap.auth.search.filter
- Whatever you type in as your login, Liferay will search for in LDAP. Liferay will determine if there is a match, according to this filter. Here are some sample filters:
  - (mail=@email_address@)
  - (screenName=@screen_name@)
  - (uid=@user_id@)
- Note: the data type for the userid is LONG, so if using userid, make sure that the field mapping to the liferay id only contains numbers, or the authentication will fail.

Frequently Asked Questions

How do I login by another field instead of an email address?

Your company may want to have users login using some value other than their email address. For example, if you have your LPAD configured and want your users to login using their another value, say their "userid" (see picture below)

For the configuration above, you would use the following settings:

    ldap.auth.enabled=true
    ldap.auth.required=true

    company.security.auth.type=screenName
    ldap.auth.search.filter=(uid=@screen_name@)
    ldap.user.mappings=screenName=uid\npassword=userPassword\nemailAddress=mail\nfirstName=givenName\nlastName=sn\njobTitle=title\ngroup=groupMembership

    ldap.user.default.object.classes=top,person,inetOrgPerson,organizationalPerson,account

This maps Liferay's "screenName" value to LDAP's "uid" value.

For example, lets say we have a user in LDAP with the userid of "112143134". Because of the properties (see above), when this user tries to log in, Liferay will try to find a user with a screenname of "112143134" using the specified search filter "(uid=@screen_name@)". When Liferay finds this user, it will import this user into Liferay according to the specified user mappings.

Liferay is ignoring the values in my portal-ext.properties file

Ive been changing the values in my portal-ext.properties file, but those changes arent reflected in the portal.. what is going on? Property values can also be set via the GUI/website. Once you "save" properties via the GUI/website, those settings will be saved in the database and those take precedence. In this case,
- 1) continue to use the GUI/website to set your property values.
- 2) manually remove those saved values from the database. WARNING.. this will remove all your saved values for authentication and you will either be using the default values, or your custom values in portal-ext.properties (if they exist). find the "portletpreferences" table, the record you want to delete will have the following values:
  - plid=0
  - portletid=LIFERAY_PORTAL
  - the "preferences" field will start with "<portlet-preferences><preference><name>ldap.base.dn</name>"

Import & Export

Import (Available since Liferay Portal 4.2)

Liferay Portal can be configured to periodically check an LDAP server and add any new user accounts to the portal database. The importer is able to:

Find new users in LDAP and add them to the portal copying the appropriate information
Update the information about existing users
Detect membership of users through groups by using a configurable attribute. LDAP groups are mapped to portal "user groups" and are created if they do not exist already

This feature is highly configurable. It is possible to define an LDAP search filter to limit which user accounts will be imported and to define the mapping of LDAP attribute names to portal profile names.

    ldap.import.enabled=true
    ldap.import.on.startup=true
    ldap.import.interval=10
    ldap.import.method=user (or group)

Liferay can import LDAP users and LDAP groups at 3 different times

Single user import on login (always)
1. If LDAP authentication has been set, user's are always automatically imported when a user logs in with LDAP credentials
2. The 1st time an LDAP user logs into Liferay, certain fields are imported (first name, last name, email, password, job title)
3. Thereafter, those fields are updated from LDAP (Since in 4.3.3)
Mass import on startup (optional)
Mass import on interval (optional)

For those interested in specific details, the implementation of this functionality is done by the classes LDAPImportJob and LDAPImportUtil.

Export (Available since Liferay Portal 4.3)

(see below for explanation of export settings)

Settings / Configuration

    ldap.import.enabled=true
    ldap.import.interval=10
    ldap.import.on.startup=true
    ldap.import.method=group

    ldap.export.enabled=false

    ldap.users.dn=ou=People,dc=localdomain
    ldap.groups.dn=ou=Groups,dc=localdomain

    ldap.user.default.object.classes=top,person,inetOrgPerson,organizationalPerson

Settings Explained

ldap.import.enabled=true
- If set to true, then Liferay will do a mass import of users on the specified interval

ldap.import.interval=10
- The number of minutes to pass before importing all LDAP users according to the import method (that match the user specified search filter) into Liferay

ldap.import.on.startup=true
- If set to true, Liferay will do a mass import of all LDAP users according to the import method (that match the user specified search filter) on startup

ldap.import.method=group
- User Import: Liferay will search and import all users.
- Group Import: Liferay will search all the groups and import the users in each group. A side effect is that all users which are NOT in a LDAP group will NOT be imported into Liferay
- Explanation:
  - When importing on an specified interval, Liferay will scan the LDAP server and import users. Since LDAP servers maintains group membership differently (2 ways, via the User and/or the Group), you can specify which method you want use to import your users.
  - LDAP Server may add attributes (most commonly the groupMembership attribute) in the user entry, specifying all the groups that the user is a member of
  - LDAP Server may add attributes (most commonly the uniqueMember attribute) in the group entry, specifying all the users that are members of the group
  - As of Liferay Portal 4.2, importing only happened via the user.
  - As of Liferay Portal 4.3.1, you now have the ldap.import.method property since Liferay can handle both methods of import'

If the user already exists in ldap.users.dn, they will be updated, otherwise a new user will be created.
Newly created users will be created with the object classes that you specify in your properties file, ldap.user.default.object.classes=top,person,inetOrgPerson,organizationalPerson.

ldap.export.enabled=false
- If set to true, Liferay will export the user to LDAP. Liferay uses a listener to track any changes made to the User object and will push these changes out to the LDAP server whenever the User object is updated. Note that on every login, fields such as "LastLoginDate" are updated and so if export is enabled, logging in with a user will export the user to LDAP.

ldap.users.dn=ou=People,dc=localdomain
- This is where Liferay will look for users (for authentication, import and export)

ldap.groups.dn=ou=Groups,dc=localdomain
- This is where Liferay will look for groups (for import)

ldap.user.default.object.classes=top,person,inetOrgPerson,organizationalPerson
- When a user is exported, the user is created with the following default object classes. To find out what your default object classes are, use a LDAP Browser tool such as OpenLdap and browse to a user and locate the ObjectClass attributes.

Frequently Asked Questions

Import

What gets imported? When importing users, Liferay searches all entries that match the following search filter. ldap.import.user.search.filter=(objectClass=inetOrgPerson) and for importing groups, Liferay searches according to the following filter: ldap.import.group.search.filter=(objectClass=groupOfUniqueNames).
Importing too much? If you want to limit what users or groups are imported, you can set ldap.users.dn=ou=users,dc=example,dc=com and ldap.groups.dn=ou=groups,dc=example,dc=com as the base.. then only users and groups under these DN's will be imported
Are there certain required fields for a LDAP user? There are 5 required user fields that Liferay needs in order for a user to be successfully imported from LDAP. Make sure that your users contain: screen name (cn), password (userPassword), email address (mail), first (givenName) and and last name (sn). The corresponding default ldap fields are in parenthesis.
Which import method should I use? Remember that you only need to deal with this when doing a mass import. If you see uniqueMember attributes in the LDAP groups, set ldap.import.method=group, otherwise set ldap.import.method=user. If set to group, Liferay will loop through all the groups, and import the users and membership that are related to each group. This means that if a user is not part of any group, that user will not be imported during a mass import. The opposite is true if set to user, groups that arent referenced by any user will not be imported.
When I delete users from LDAP, they are not being deleted in Liferay. Why? Currently, the LDAP import will only import new users. To remove users from Liferay, you can use Liferay's Enterprise Admin Portlet to "deactivate" or "delete" users.
What happens during a interval import? All (new and old) LDAP users are pulled into Liferay, new LDAP groups are pulled into Liferay as UserGroups and user to group membership is synchronized (users are added and removed from userGroups)

Export

Liferay is only exporting a few of my fields, how can I export all my fields? Currently, only a limited number of fields are pushed out to LDAP (screenName, password, emailAddress, firstName and lastName).
How can I export user groups? Currently, group export is not supported.
Why do I get errors when trying to login while export is enabled? One possible reason is that your UsersDN is not set correctly. When using export, all uses must reside directly in UsersDN.

Bugs & Fixes

LEP-3626 - After a successful login, the LDAP user will be imported into Liferay. However, the password wasnt being imported correctly. This issue has been fixed. See support ticket for temporary work around.
LEP-3607 - After a successful login, the LDAP user will be imported into Liferay. Liferay thought this import meant that the password was being updated.. and when the password was the same.. it complained saying you arent allowed the change the password with the same password. This issue has been fixed.
LPS-3786 - Export of blank job title fails with javax.naming.directory.InvalidAttributeValueException - LDAP error code 21.

Additional Features

LDAP Password Policy (Available since Liferay Portal 4.3)

Password Policies have been introduced to Liferay Portal beginning in version 4.3. The default setting is for the portal to use a local password policy, but the portal can also be configured to use LDAP password policies.

By default, a local "Default Password Policy" is created for you (as seen in the Enterprise Admin Portlet).

To configure the Portal to use LDAP's password policy, go to

> Enterprise Admin Portlet
> "Settings" tab
> "Authentication" tab
> "LDAP" tab
> and under the "Password Policy" tab, click the "Use LDAP Password Policy" checkbox on (at the bottom)

If that has been done correctly, when you try and view the Password Policy, you will get a message saying that you are not using a local password policy

Settings / Configuration

    #
    # Set this to true to use the LDAP's password policy instead of the portal
    # password policy.
    #
    ldap.password.policy.enabled=false

    #
    # Set these values to be a portion of the error message returned by the
    # appropriate directory server to allow the portal to recognize messages
    # from the LDAP server. The default values will work for Fedora DS.
    #
    ldap.error.password.age=age
    ldap.error.password.expired=expired
    ldap.error.password.history=history
    ldap.error.password.not.changeable=not allowed to change
    ldap.error.password.syntax=syntax
    ldap.error.password.trivial=trivial
    ldap.error.user.lockout=retry limit

Settings Explained

ldap.password.policy.enabled
- If set to true, Liferay will use LDAP's password policy instead of a local password policy

ldap.error....
- Set these values to be a portion of the error message returned by the appropriate directory server to allow the portal to recognize messages from the LDAP server. The default values are known to work for Fedora DS.

Frequently Asked Questions

(add any questions you may have here)

Changes in Liferay Portal LDAP Settings

excerpt from portal.properties in Liferay Portal 4.2

Following are the properties to set it up in Liferay Portal 4.2 (note that this configuration has changed in the upcoming Liferay Portal 4.3, check the new portal.properties for the new configuration):

 ##
 ## LDAP Import
 ##
    ldap.import.enabled=false
    ldap.import.on.startup=false
    #
    # Enter time in minutes. This is how often the importer will synchronize
    # with LDAP. This property is portal wide. Company override will be ignored.
    #
    ldap.import.interval=10
    ldap.import.factory.initial=com.sun.jndi.ldap.LdapCtxFactory
    ldap.import.base.provider.url=ldap://localhost:10389
    ldap.import.base.dn=dc=example,dc=com
    ldap.import.security.principal=uid=admin,ou=system
    ldap.import.security.credentials=secret
    ldap.import.search.filter=(objectClass=inetOrgPerson)
    ldap.import.user.mappings=userId=cn\npassword=userPassword\nemailAddress=mail\nfirstName=givenName\nlastName=sn\njobTitle=title\ngroup=groupMembership
    ldap.import.group.mappings=groupName=cn\ndescription=description

excerpt from portal.properties in Liferay Portal 4.3

##
## LDAP
##

    #
    # Set the values used to connect to a LDAP store.
    #
    ldap.factory.initial=com.sun.jndi.ldap.LdapCtxFactory
    ldap.base.provider.url=ldap://localhost:10389
    ldap.base.dn=dc=example,dc=com
    ldap.security.principal=uid=admin,ou=system
    ldap.security.credentials=secret

    #
    # Settings for com.liferay.portal.security.auth.LDAPAuth can be configured
    # from the Admin portlet. It provides out of the box support for Apache
    # Directory Server, Microsoft Active Directory Server, Novell eDirectory,
    # and OpenLDAP. The default settings are for Apache Directory Server.
    #
    # The LDAPAuth class must be specified in the property "auth.pipeline.pre"
    # to be executed.
    #
    # Encryption is implemented by com.liferay.util.Encryptor.provider.class in
    # system.properties.
    #
    ldap.auth.enabled=false
    ldap.auth.required=false

    #
    # Set either bind or password-compare for the LDAP authentication method.
    # Bind is preferred by most vendors so that you don't have to worry about
    # encryption strategies.
    #
    ldap.auth.method=bind

    #
    # Active Directory stores information about the user account as a series of
    # bit fields in the UserAccountControl attribute.
    #
    # If you want to prevent disabled accounts from logging into the portal you
    # need to use a search filter similiar to the following:
    # (&(objectclass=person)(userprincipalname=@email_address@)(!(UserAccountControl:1.2.840.113556.1.4.803:=2)))
    #
    # See the following links:
    #     [http://support.microsoft.com/kb/305144/]
    #     [http://support.microsoft.com/?kbid=269181]
    #
    ldap.auth.search.filter=(mail=@email_address@)
    ldap.auth.password.encryption.algorithm=
    ldap.auth.password.encryption.algorithm.types=MD5,SHA

    #
    # The following settings are used to map LDAP users to portal users.
    #
    # You can write your own class that extends
    # com.liferay.portal.security.ldap.LDAPUser to customize the behavior for
    # exporting portal users to the LDAP store.
    #
    ldap.users.dn=dc=example,dc=com
    #ldap.users.dn=ou=users,dc=example,dc=com
    ldap.user.mappings=screenName=cn\npassword=userPassword\nemailAddress=mail\nfirstName=givenName\nlastName=sn\njobTitle=title\ngroup=groupMembership
    ldap.user.impl=com.liferay.portal.security.ldap.LDAPUser
    ldap.user.default.object.classes=top,person,inetOrgPerson,organizationalPerson

    #
    # The following settings are used to map LDAP groups to portal user groups.
    #
    ldap.groups.dn=ou=groups,dc=example,dc=com
    ldap.group.mappings=groupName=cn\ndescription=description\nuser=uniqueMember

    #
    # Settings for importing users and groups from LDAP to the portal.
    #
    ldap.import.enabled=false
    ldap.import.on.startup=false
    ldap.import.interval=10
    ldap.import.user.search.filter=(objectClass=inetOrgPerson)
    ldap.import.group.search.filter=(objectClass=groupOfUniqueNames)

    #
    # Set either user or group for import method. If set to user, portal will
    # import all users and the groups associated with those users. If set to
    # group, the portal import all groups and the users associated those groups.
    # This value should be set based on how your LDAP server stores group
    # membership information.
    #
    ldap.import.method=user
    #ldap.import.method=group

    #
    # Settings for exporting users from the portal to LDAP. This allows a user
    # to modify his first name, last name, etc. in the portal and have that
    # change get pushed to the LDAP server. This will only be active if the
    # property "ldap.auth.enabled" is also set to true.
    #
    ldap.export.enabled=true

    #
    # Set this to true to use the LDAP's password policy instead of the portal
    # password policy.
    #
    ldap.password.policy.enabled=false

    #
    # Set these values to be a portion of the error message returned by the
    # appropriate directory server to allow the portal to recognize messages
    # from the LDAP server. The default values will work for Fedora DS.
    #
    ldap.error.password.age=age
    ldap.error.password.expired=expired
    ldap.error.password.history=history
    ldap.error.password.not.changeable=not allowed to change
    ldap.error.password.syntax=syntax
    ldap.error.password.trivial=trivial
    ldap.error.user.lockout=retry limit

Suggestions

A very helpful tool in configuring LDAP would be to build something to the effect of a LDAP configuration wizard. This should display some basic information:

Step 1. Connection settings
- Connection to LDAP (success/fail)
Step 2. User and Group mappings
- Users found (x users found)
- UserGroups (x groups found)
Step 3. Test user authentication
- (a mini login portlet) where you can input login and password.. and it will tell you if you connected successfully

Troubleshooting

The best way to learn how to set up the Liferay LDAP integration is to check the available Lifecast at:

http://www.liferay.com/web/guest/documentation/4_2/installation_and_customization

(Direct link to the last version of the lifecast at the time of writting this: ldap .swf)

You can use tools like JXplorer to browse your LDAP server:

http://www.jxplorer.org/

Recommended comprobations

Check the port where the LDAP server is running and make sure it matches Liferay's configuration. The default is 10389
Check the baseDN of the LDAP server and make sure it matches Liferay's configuration. The default is dc=example,dc=com
Turn on all debug information through the Admin portlet
Use wireshark or a similar tool to spy on the LDAP network traffic between Liferay and the LDAP server

How to log in if integration is broken

Omniadmin users are allowed to log in even if the integration with LDAP is broken. This allows to use this administrator accounts to fix the problem. The default user created with liferay (test@liferay.com) is an example of an omniadmin users. Others can be configured in portal.properties (or portal-ext.properties) indicating a comma separated list of user ids:

4.2.X and before

 omniadmin.users=liferay.com.1,liferay.com.1001

4.3.X

 omniadmin.users=2,12345,98765

Unit Test

To make sure that LDAP integration is working with the version of the sources that you are using (if not using a stable version) you can run LDAP from the test package:

 ant test-ldap

Links

Lifecast on LDAP

Directory Operations JNDI

Acegi Security for Liferay

Liferay 4.x.x Portal Architecture

Single SignOn - Integrating Liferay With CAS Server

Children Pages

Open DS Configuration

18994 Views ,

0 Attachments

Average (0 Votes)

I have a problem with: "For example, lets say we...

Piotr Pietrzak

11/4/09 10:14 PM

Comments

Piotr Pietrzak

I have a problem with:
"For example, lets say we have a user in LDAP with the userid of "112143134". Because of the properties (see above), when this user tries to log in, Liferay will try to find a user with a screenname of "112143134" using the specified search filter "(uid=@screen_name@)". When Liferay finds this user, it will import this user into Liferay according to the specified user mappings."
This is not true, bacause screen_name can not be a number.
UserLocalServiceImpl.java :
if (Validator.isNumber(screenName) &&
!screenName.equals(String.valueOf(userId))) {

throw new UserScreenNameException();
}
Is there a quick solution for this problem?

Posted on 11/4/09 10:14 PM.

±0
(0 Votes) Sign in to vote.

Top

Liferay.com

Contact Us

Wiki

LDAP

Table of Contents [-+]

Overview

Set up

via GUI

via portal.properties

Connection Settings

Settings Explained

Check Point

Connecting to LDAP over SSL

Authentication

Settings / Configuration

Settings Explained

Frequently Asked Questions

How do I login by another field instead of an email address?

Liferay is ignoring the values in my portal-ext.properties file

Import & Export

Import (Available since Liferay Portal 4.2)

Export (Available since Liferay Portal 4.3)

Settings / Configuration

Settings Explained

Frequently Asked Questions

Import

Export

Bugs & Fixes

Additional Features

LDAP Password Policy (Available since Liferay Portal 4.3)

Settings / Configuration

Settings Explained

Frequently Asked Questions

Changes in Liferay Portal LDAP Settings

excerpt from portal.properties in Liferay Portal 4.2

excerpt from portal.properties in Liferay Portal 4.3

Suggestions

Troubleshooting

Recommended comprobations

How to log in if integration is broken

Unit Test

Links

Related Articles

Children Pages

I have a problem with: "For example, lets say we...