LDAP
From LiferayPedia
This page seeks to explain LDAP's use in Liferay.
Contents[hide] |
Features
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 pipline:
auth.pipeline.pre=com.liferay.portal.security.auth.LDAPAuth
You can set default values in portal.properties as well:
# # 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. # auth.impl.ldap.enabled=false auth.impl.ldap.required=false auth.impl.ldap.factory.initial=com.sun.jndi.ldap.LdapCtxFactory auth.impl.ldap.provider.url=ldap://localhost:10389/dc=example,dc=com auth.impl.ldap.security.principal=uid=admin,ou=system auth.impl.ldap.security.credentials=secret auth.impl.ldap.search.filter=(mail=@email_address@) auth.impl.ldap.user.mappings=userId=cn\npassword=userPassword\nemailAddress=mail\nfirstName=givenName\nlastName=sn\njobTitle=title
Import
...
Export
...
Password Policy
...
Import (Available since Liferay Portal 4.2)
LDAP Import Settings
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)
LDAP Import Details
Liferay can import LDAP users and LDAP groups at 3 different times
- Single user import on login (required)
- Mass import on startup (optional)
- Mass import on interval (optional)
- If LDAP authentication has been set, user's are automatically imported when a user logs in with LDAP credentials
- LDAP servers can maintains group membership in 2 different ways, via the User and/or the Group.
- 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
- You only need to deal with this when doing a mass import. To work with this, you will need to set another property, ldap.import.method. 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.
- 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
- 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
Export (Available since Liferay Portal 4.3)
LDAP Export Settings
The following properties are used in LDAP export
ldap.export.enabled=true 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
LDAP Export Details
- If ldap.export.enabled=true, 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.
- 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.
- Currently, only a limited number of fields are pushed out to LDAP (screenName, password, emailAddress, firstName, lastName and jobTitle).
- Currently, groups can not be exported.
Password Policy (LDAP)
...
LDAP Settings in Liferay Portal
excerpt of 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 of 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
For those interested in specific details, the implementation of this functionality is done by the classes LDAPImportJob and LDAPImportUtil.
Set up
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:
Troubleshooting
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
- Check
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:
omniadmin.users=liferay.com.1,liferay.com.1001
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