Old LDAP Authenticator

Last modified by Thomas Mortagne on 2018/02/09

This documentation is dedicated to the old LDAP authenticator which has been removed from XWiki in 8.3. It's highly recommended to use LDAP Authenticator extension instead for any version of XWiki higher or equal to 7.4.

Generic LDAP configuration

If you are going to use the LDAP Admin Extension, which makes it easier to configure LDAP, then you only need to uncomment xwiki.authentication.authclass property and nothing else. Unlike editing xwiki.cfg, which requires you to redeploy the XWiki webapp, LDAP Extension allows you to make changes without restarting. 

In order to enable the LDAP support you have to change the authentication method in WEB-INF/xwiki.cfg as follows:

#-# LDAP authentication service
# xwiki.authentication.authclass=com.xpn.xwiki.user.impl.LDAP.XWikiLDAPAuthServiceImpl

#-# Turn LDAP authentication on - otherwise only XWiki authentication
#-# - 0: disable
#-# - 1: enable
#-# The default is 0
# xwiki.authentication.ldap=1

You can setup the LDAP configuration in the xwiki.cfg file by filling the following properties:

#-# Turn LDAP authentication on - otherwise only XWiki authentication
#-# - 0: disable
#-# - 1: enable
#-# The default is 0
# xwiki.authentication.ldap=1

#-# LDAP Server (Active Directory, eDirectory, OpenLDAP, etc.)
xwiki.authentication.ldap.server=127.0.0.1
xwiki.authentication.ldap.port=389

#-# LDAP login, empty = anonymous access, otherwise specify full dn
#-# {0} is replaced with the user name, {1} with the password
xwiki.authentication.ldap.bind_DN=cn={0},department=USER,department=INFORMATIK,department=1230,o=MP
xwiki.authentication.ldap.bind_pass={1}

#-# The Base DN used in LDAP searches
xwiki.authentication.ldap.base_DN=

#-# LDAP query to search the user in the LDAP database (in case a static admin user is provided in
#-# xwiki.authentication.ldap.bind_DN)
#-# {0} is replaced with the user uid field name and {1} with the user name
#-# The default is ({0}={1})
# xwiki.authentication.ldap.user_search_fmt=({0}={1})

#-# Only members of the following group can authenticate.
#-# The following kind of groups are supported:
#-# * LDAP static groups (users/subgroups are listed statically in the group object)
#-# * [Since 3.3M1] LDAP organization units (users/subgroups are sub object of the provided organization unit)
#-# * [Since 3.3M1] LDAP filter (users/groups are object found in a search with the provided filter)
# xwiki.authentication.ldap.user_group=cn=developers,ou=groups,o=MegaNova,c=US

#-# [Since 1.5RC1, XWikiLDAPAuthServiceImpl]
#-# Only users not member of the following group can authenticate.
#-# The following kind of groups are supported:
#-# * LDAP static groups (users/subgroups are listed statically in the group object)
#-# * [Since 3.3M1] LDAP organization units (users/subgroups are sub object of the provided organization unit)
#-# * [Since 3.3M1] LDAP filter (users/groups are object found in a search with the provided filter)
# xwiki.authentication.ldap.exclude_group=cn=admin,ou=groups,o=MegaNova,c=US

#-# Specifies the LDAP attribute containing the identifier to be used as the XWiki name
#-# The default is cn
# xwiki.authentication.ldap.UID_attr=cn

#-# [Since 1.5M1, XWikiLDAPAuthServiceImpl]
#-# The potential LDAP groups classes. Separated by commas.
# xwiki.authentication.ldap.group_classes=group,groupOfNames,groupOfUniqueNames,dynamicGroup,dynamicGroupAux,groupWiseDistributionList,posixGroup,apple-group

#-# [Since 1.5M1, XWikiLDAPAuthServiceImpl]
#-# The potential names of the LDAP groups fields containings the members. Separated by commas. 
# xwiki.authentication.ldap.group_memberfields=member,uniqueMember,memberUid

#-# retrieve the following fields from LDAP and store them in the XWiki user object (xwiki-attribute=ldap-attribute)
xwiki.authentication.ldap.fields_mapping=last_name=sn,first_name=givenName,email=mail

#-# [Since 1.3M2, XWikiLDAPAuthServiceImpl]
#-# On every login update the mapped attributes from LDAP to XWiki otherwise this happens only once when the XWiki
#-# account is created.
#-# - 0: only when creating user
#-# - 1: at each authentication
#-# The default is 0
xwiki.authentication.ldap.update_user=1

#-# [Since 8.1M2, XWikiLDAPAuthServiceImpl]
#-# On every login update photo from LDAP to XWiki avatar otherwise photo will not be updated.
#-# - 0: never
#-# - 1: at each authentication
#-# The default is 0
# xwiki.authentication.ldap.update_photo=0

#-# [Since 8.1M2, XWikiLDAPAuthServiceImpl]
#-# Profile attachment name which will be used to save LDAP photo.
#-# The default is ldapPhoto
# xwiki.authentication.ldap.photo_attachment_name=ldapPhoto

#-# [Since 8.1M2, XWikiLDAPAuthServiceImpl]
#-# Specifies the LDAP attribute containing the binary photo
#-# The default is thumbnailPhoto
# xwiki.authentication.ldap.photo_attribute=thumbnailPhoto

#-# [Since 1.3M2, XWikiLDAPAuthServiceImpl]
#-# Maps XWiki groups to LDAP groups, separator is "|".
#-# The following kind of groups are supported:
#-# * LDAP static groups (users/subgroups are listed statically in the group object)
#-# * [Since 3.3M1] LDAP organization units (users/subgroups are sub object of the provided organization unit)
#-# * [Since 3.3M1] LDAP filter (users/groups are object found in a search with the provided filter),
#-#   | character in the filter need to be escaped with backslash (\).
#-#
#-# Here is an example:
# xwiki.authentication.ldap.group_mapping=XWiki.XWikiAdminGroup=cn=AdminRole,ou=groups,o=domain,c=com|\
#                                         XWiki.LDAPUsers=ou=groups,o=domain,c=com|\
#                                         XWiki.Organisation=(cn=testers)

#-# [Since 1.3M2, XWikiLDAPAuthServiceImpl]
#-# Time in s after which the list of members in a group is refreshed from LDAP
#-# The default is 21600 (6 hours)
# xwiki.authentication.ldap.groupcache_expiration=21600

#-# [Since 1.3M2, XWikiLDAPAuthServiceImpl]
#-# - create : synchronize group membership only when the user is first created
#-# - always: synchronize on every login
#-# The default is always
# xwiki.authentication.ldap.mode_group_sync=always

#-# [Since 7.2M3, XWikiLDAPAuthServiceImpl]
#-# Indicate groups members should be resolved in case they are subgroups.
#-# Doing so can be very expensive so it should be disabled if you know there is no subgroups
#-# (or if you don't care about them).
#-# If the group is actually a filter it will always be resolved since it does not make sense left alone.
#-# - 0: disable
#-# - 1: enable
#-# The default is 1
# xwiki.authentication.ldap.group_sync_resolve_subgroups=0

#-# [Since 1.3M2, XWikiLDAPAuthServiceImpl]
#-# If ldap authentication fails for any reason, try XWiki DB authentication with the same credentials
#-# - 0: disable
#-# - 1: enable
#-# The default is 0
xwiki.authentication.ldap.trylocal=1

#-# [Since 1.3M2, XWikiLDAPAuthServiceImpl]
#-# SSL connection to LDAP server
#-# - 0: normal
#-# - 1: SSL
#-# The default is 0
# xwiki.authentication.ldap.ssl=0

#-# [Since 1.3M2, XWikiLDAPAuthServiceImpl]
#-# The keystore file to use in SSL connection
# xwiki.authentication.ldap.ssl.keystore=

#-# [Since 1.5M1, XWikiLDAPAuthServiceImpl]
#-# The java secure provider used in SSL connection
#-# The default is com.sun.net.ssl.internal.ssl.Provider
# xwiki.authentication.ldap.ssl.secure_provider=com.sun.net.ssl.internal.ssl.Provider

#-# Bypass standard LDAP bind validation by doing a direct password comparison.
#-# If you don't know what you do, don't use that. It's covering very rare and bad use cases.
#-# - 0: disable
#-# - 1: enable
#-# The default is 0
# xwiki.authentication.ldap.validate_password=0

#-# [Since 1.5M1, XWikiLDAPAuthServiceImpl]
#-# Specifies the LDAP attribute containing the password to be used "when xwiki.authentication.ldap.validate_password"
#-# is set to 1
# xwiki.authentication.ldap.password_field=userPassword

#-# [Since 4.3M1, XWikiLDAPAuthServiceImpl]
#-# The maximum number of milliseconds the client waits for any operation under these constraints to complete.
#-# The default is 1000
# xwiki.authentication.ldap.timeout=1000

#-# [Since 6.3M1, XWikiLDAPAuthServiceImpl]
#-# The maximum number of search results to be returned from a search operation.
#-# The default is 1000
# xwiki.authentication.ldap.maxresults=1000

You can also setup the LDAP configuration in the XWiki.XWikiPreferences page by going to the object editor. Simply replace xwiki.authentication.ldap. with ldap_. For example xwiki.authentication.ldap.base_DN becomes ldap_base_DN.

LDAP clients

For testing purposes, you may wish to omit the "ldap.fields_mapping" field, to test the authentication first, and then add it later to get the mappings right.

Here are some LDAP clients for checking your configuration:

Extensions:

Java based and Open Source:

Windows only:

Detailed use cases

See the LDAP configuration uses cases for some detailed use cases.

Enable LDAP debug log

See Logging.

The specific packages to track for LDAP are com.xpn.xwiki.plugin.ldap and com.xpn.xwiki.user.impl.LDAP.

Starting with XWiki 4.2 we added a new Logging UI from the Administration section, which allows logging to be enabled at runtime, directly from the UI, without the need to restart the wiki.

In XWiki 3.4 you need to add the following in WEB-INF/classes/logback.xml:

<!-- LDAP debugging -->
<logger name="com.xpn.xwiki.plugin.ldap" level="trace"/>
<logger name="com.xpn.xwiki.user.impl.LDAP" level="trace"/>

Before 3.1, add the following to the log4j configuration file:

log4j.logger.com.xpn.xwiki.plugin.ldap=trace
log4j.logger.com.xpn.xwiki.user.impl.LDAP=trace
Tags:
   

Get Connected