LDAP Authenticator

Last modified by Admin on 2024/02/05 00:18

cogAuthenticate using a LDAP server
Recommended
TypeJAR
CategoryAuthenticator
Developed by

Denis Gervalle, Thomas Mortagne, Alex Cotiuga, XWiki Development Team

Active Installs1019
Rating
3 Votes
LicenseGNU Lesser General Public License 2.1
Compatibility

This extension was bundled by default in XWiki Enterprise till XWiki 8.2.x. It's been moved out and made optional starting with XWiki 8.3M1.

Require XWiki 8.4 or more.

Installable with the Extension Manager

Description

If you're interested in connecting XWiki with Active Directory you may be interested in the Active Directory Application, which is a paying application dedicated to simplifying the integration of Active Directory with XWiki. The Active Directory Application allows you to easily connect your Active Directory server to XWiki using a visual editor, update advanced configuration settings without restarting the application server, technical support provided by XWiki SAS, etc.
Otherwise you can install this generic LDAP extension and configure it for Active Directory.

Release notes can be found on LDAP project page.

In order to use the LDAP Application (which provides a more visual way to configure LDAP) then you need to set the xwiki.authentication.authclass and the xwiki.authentication.ldap.trylocal properties, the rest can be set using the UI. Unlike editing xwiki.cfg, LDAP Application allows you to make changes without restarting the application server.

Generic LDAP configuration

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

#-# LDAP authentication service
xwiki.authentication.authclass=org.xwiki.contrib.ldap.XWikiLDAPAuthServiceImpl

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

#-# Enable local accounts in addition to LDAP.
#-# Without this setting you will be unable to log into XWiki with local accounts.
#-# - 0: disable
#-# - 1: enable
#-# The default is 0
xwiki.authentication.ldap.trylocal=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.)
#-# The default host is localhost
xwiki.authentication.ldap.server=localhost
#-# The default port is 389 (636 if xwiki.authentication.ldap.ssl is enabled)
# xwiki.authentication.ldap.port=389

#-# LDAP credentials, 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:
# 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

#-# 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 unique user identifier. It's also used by default as identifier on XWiki side for the user profile page name.
#-# The default is:
# xwiki.authentication.ldap.UID_attr=cn

#-# The potential LDAP groups classes. Separated by commas.
#-# The default is group,groupOfNames,groupOfUniqueNames,dynamicGroup,dynamicGroupAux,groupWiseDistributionList,posixGroup,apple-group
# xwiki.authentication.ldap.group_classes=group,groupOfNames,groupOfUniqueNames,dynamicGroup,dynamicGroupAux,groupWiseDistributionList,posixGroup,apple-group

#-# The potential names of the LDAP groups fields containings the members. Separated by commas.
#-# The default is member,uniqueMember,memberUid
# 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).
#-# You can add any custom field you want in the XWiki user profile in the user profile section of the wiki administration.
#-# You can find all the field defined in the user profile in the page XWiki.XWikiUsers and here are some of the important ones:
#-# * first_name
#-# * last_name
#-# * email
#-# * company
#-# * address
#-# * phone
#-# * comment (a free form text about the user)
#-# By default the list is empty
xwiki.authentication.ldap.fields_mapping=last_name=sn,first_name=givenName,email=mail

#-# On every authentication 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

#-# On every authentication 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

#-# Profile attachment name which will be used to save LDAP photo.
#-# The default is ldapPhoto
# xwiki.authentication.ldap.photo_attachment_name=ldapPhoto

#-# Specifies the LDAP attribute containing the binary photo
#-# The default is thumbnailPhoto
# xwiki.authentication.ldap.photo_attribute=thumbnailPhoto

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

#-# 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

#-# - create : synchronize group membership only when the user is first created
#-# - always: synchronize on every authentication
#-# The default is always
# xwiki.authentication.ldap.mode_group_sync=always

#-# 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

#-# SSL connection to LDAP server
#-# - 0: normal
#-# - 1: SSL
#-# The default is 0
# xwiki.authentication.ldap.ssl=0

#-# The keystore file to use in SSL connection
# xwiki.authentication.ldap.ssl.keystore=

#-# Set a specific java secure provider to be used in SSL connection, besides the already preregistered ones.
# xwiki.authentication.ldap.ssl.secure_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

#-# 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

#-# The maximum number of milliseconds the client waits for any operation under these constraints to complete.
#-# The default (0) is no timeout
# xwiki.authentication.ldap.timeout=0

#-# The maximum number of search results to be returned from a search operation.
#-# The default is 1000
# xwiki.authentication.ldap.maxresults=1000

#-# An HTTP Header to be use as the authenticated remote user input (in place of using the default authenticated user reported by the servlet container)
#-# WARNING: Enabling this feature without ensuring the validity of transmitted headers is very insecure.
#-#
#-# In this example, the authenticated user will be taken from the HTTP header REMOTE_USER:
# xwiki.authentication.ldap.httpHeader=REMOTE_USER

#-# A Java regexp used to parse the remote user provided by JAAS.
#-# 
#-# The following matches the users like UID@DOMAIN:
# xwiki.authentication.ldap.remoteUserParser=(.+)@(.+)

#-# Indicate which of the regexp group correspond to which LDAP properties.
#-# The following LDAP properties are reserved (any other property can be defined as variable for xwiki.authentication.ldap.userPageName):
#-#   * uid: the uid of the user
#-#   * password: the password of the user
#-#   * all the non multidomain related properties with "ldap_" prefix (ldap_server, ldap_port, ldap_base_DN, etc.) 
#-# 
#-# The following indicate that the first regexp group is associated to the uid:
# xwiki.authentication.ldap.remoteUserMapping.1=uid
#-# The following indicate that the second regexp group is associated everything else we want to make different based on the domain (the mapping is then used to indicate which is the value for each property):
# xwiki.authentication.ldap.remoteUserMapping.2=domain,ldap_server,ldap_port,ldap_base_DN,ldap_bind_DN,ldap_bind_pass,ldap_group_mapping

#-# Indicate how to convert each found property. If a property is not set, the standard LDAP authenticator setup is used.
#-# 
#-# Here is an example mapping each of the domains MYDOMAIN and MYDOMAIN2 to specific properties:
# xwiki.authentication.ldap.remoteUserMapping.ldap_server=MYDOMAIN=my.domain.com|MYDOMAIN2=my.domain2.com
# xwiki.authentication.ldap.remoteUserMapping.ldap_port=MYDOMAIN=388|MYDOMAIN2=387
# xwiki.authentication.ldap.remoteUserMapping.ldap_base_DN=MYDOMAIN=dc=my,dc=domain,dc=com|MYDOMAIN2=dc=my,dc=domain2,dc=com
# xwiki.authentication.ldap.remoteUserMapping.ldap_bind_DN=MYDOMAIN=cn=bind,dc=my,dc=domain,dc=com|MYDOMAIN2=cn=bind,dc=my,dc=domain2,dc=com
# xwiki.authentication.ldap.remoteUserMapping.ldap_bind_pass=MYDOMAIN=password|MYDOMAIN2=password2
# xwiki.authentication.ldap.remoteUserMapping.ldap_group_mapping=MYDOMAIN=XWiki.Admin=cn=admin,dc=my,dc=domain,dc=com\\|XWiki.LDAPUsers=ou=groups,o=domain,c=com|MYDOMAIN2=XWiki.Admin=cn=admin,dc=my,dc=domain2,dc=com\\|XWiki.LDAPUsers=ou=groups,o=domain2,c=com

#-# The XWiki page name pattern.
#-# The supported syntax is org.apache.commons.lang3.text.StrSubstitutor one,
#-# see http://commons.apache.org/proper/commons-lang/javadocs/api-3.0/org/apache/commons/lang3/text/StrSubstitutor.html for more details.
#-# Can use:
#-# * the LDAP fields listed in xwiki.authentication.ldap.fields_mapping by prefixing it with "ldap." as in ${ldap.givenName}
#-# * xwiki.authentication.ldap.remoteUserParser regex groups
#-# * a properties defined in xwiki.authentication.ldap.remoteUserMapping
#-# 
#-# The following suffixes can be added:
#-# * "._lowerCase": the lower case version of the string
#-# * "._upperCase": the upper case version of the string 
#-# * "._clean": a version of the string stripped from ".", ":", ",", "@", "^", "/" characters and "\s" (all forms of white spaces).
#-#             It can itself be suffixed with "._lowerCase" and "._upperCase".
#-#
#-# In this example the XWiki user profile page name will be of the form MYDOMAIN-myuid
# xwiki.authentication.ldap.userPageName=${domain}-${uid}
#-#
#-# The default is; "${uid}".
# xwiki.authentication.ldap.userPageName=${uid}

#-# The list of authentication inputs for which user profile should also be searched based on uid.
#-# You can use this property as retro-compatibility when upgrading a setup that used to be targeting a single LDAP server.
#-# An alternative is to change the uid in all the existing users to make sure it contains complete input instead.
#-# 
#-# In this example the authenticator will try to find existing users from domain MYDOMAIN with only the uid when it can't find one with the complete input:
# xwiki.authentication.ldap.testLoginFor=${uid}@MYDOMAIN,${uid}@ANOTHERDOMAIN

#-# The maximum number of results to receive at the same time in a pages search (for example when searching group members).
#-# The default is 500.
#-# 
# xwiki.authentication.ldap.searchPageSize=500

#-# Discover SRV records at _ldap._tcp.<xwiki.authentication.ldap.server>  (or _ldaps._tcp.<xwiki.authentication.ldap.server> if ssl is enabled) and use the one with the highest priority/weight. If no record is found, proceed to connect to <xwiki.authentication.ldap.server>.
#-# The default is 1.
#-# 
# xwiki.authentication.ldap.service_discovery=1

#-# In some cases the referral setup of an LDAP server is not is a great shape but cannot be easily changed and you which you could just tell the authenticator to ignore those.
#-# By default referral following is enabled (1) but it can be disabled with 0 and the authenticator will simply ignore any referral related error (but log them in debug mode) and continue.
#-# 
# xwiki.authentication.ldap.follow_referrals=1

It's also possible to put any of theses configuration in the XWiki.XWikiPreferences object in the XWiki.XWikiPreferences page. Add a string field with the proper name to the class and put the value you want.

The fields names are not exactly the same, you have to change "xwiki.authentication.ldap." prefix to "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.

FAQ

Why is the user/group not updated?

The default setting is to synchronize the users and groups after authentication:

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

Enable LDAP debug log

When authentication still does not work and you have no clue why it's generally a good idea to enable debug log to get in your application server log a step by step of everything the authenticator does and its struggles.

See Logging.

The specific packages to track for LDAP is org.xwiki.contrib.ldap. There is several ways to enable debug log.

With the Logging Admin UI

Use Logging Admin UI from the Administration section, add set TRACE or DEBUG level classes located in package org.xwiki.contrib.ldap.

Anything you set trough the Logging Administration won't be remembered after a restart.

With the Logback configuration file

You need to add the following in WEB-INF/classes/logback.xml:

<!-- LDAP debugging -->
<logger name="org.xwiki.contrib.ldap" level="trace"/>

After this change you will need to restart XWiki.

Release Notes

This is the release note of the whole LDAP project. All release notes

9.13.1

The following translations have been updated with this release:

9.13.0

9.12.0

9.11.3

The following translations have been updated with this release:

9.11.2

The following translations have been updated with this release:

9.11.1

More debug log.

9.11.0

9.10.1

9.10

9.9.1

9.9.0

9.8.0

9.7.8

The following translations have been updated with this release:

9.7.7

9.7.6

9.7.5

9.7.4

9.7.3

9.7.2

9.7.1

9.7

...

8.3.x

Convert to contrib extension.

New class for the authenticator:

xwiki.authentication.authclass=org.xwiki.contrib.ldap.XWikiLDAPAuthServiceImpl

And in general all classes are similar but have been moved to the new org.xwiki.contrib.ldap package. Old classes still exist in the Legacy Authenticator.

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).

You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.

Dependencies

Dependencies for this extension (org.xwiki.contrib.ldap:ldap-authenticator 9.13.1):

  • org.xwiki.platform:xwiki-platform-oldcore 8.4
  • com.novell.ldap:jldap 2009-10-07
  • org.xwiki.contrib:authservice-backport-api 1.1.1
Tags:
    

Get Connected