Wiki source code of Old LDAP Authenticator

Last modified by Thomas Mortagne on 2018/02/09

Show last authors
1 {{warning}}
2 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>>extensions:Extension.LDAP.Authenticator]] instead for any version of XWiki higher or equal to 7.4.
3 {{/warning}}
4
5 == Generic LDAP configuration ==
6
7 If you are going to use the [[LDAP Admin Extension>>extensions:Extension.LDAP.Application]], 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.
8
9 In order to enable the LDAP support you have to change the authentication method in //WEB-INF/xwiki.cfg// as follows:
10
11 {{code language="properties"}}
12 #-# LDAP authentication service
13 # xwiki.authentication.authclass=com.xpn.xwiki.user.impl.LDAP.XWikiLDAPAuthServiceImpl
14
15 #-# Turn LDAP authentication on - otherwise only XWiki authentication
16 #-# - 0: disable
17 #-# - 1: enable
18 #-# The default is 0
19 # xwiki.authentication.ldap=1
20 {{/code}}
21
22 You can setup the LDAP configuration in the **xwiki.cfg** file by filling the following properties:
23
24 {{code language="properties"}}
25 #-# Turn LDAP authentication on - otherwise only XWiki authentication
26 #-# - 0: disable
27 #-# - 1: enable
28 #-# The default is 0
29 # xwiki.authentication.ldap=1
30
31 #-# LDAP Server (Active Directory, eDirectory, OpenLDAP, etc.)
32 xwiki.authentication.ldap.server=127.0.0.1
33 xwiki.authentication.ldap.port=389
34
35 #-# LDAP login, empty = anonymous access, otherwise specify full dn
36 #-# {0} is replaced with the user name, {1} with the password
37 xwiki.authentication.ldap.bind_DN=cn={0},department=USER,department=INFORMATIK,department=1230,o=MP
38 xwiki.authentication.ldap.bind_pass={1}
39
40 #-# The Base DN used in LDAP searches
41 xwiki.authentication.ldap.base_DN=
42
43 #-# LDAP query to search the user in the LDAP database (in case a static admin user is provided in
44 #-# xwiki.authentication.ldap.bind_DN)
45 #-# {0} is replaced with the user uid field name and {1} with the user name
46 #-# The default is ({0}={1})
47 # xwiki.authentication.ldap.user_search_fmt=({0}={1})
48
49 #-# Only members of the following group can authenticate.
50 #-# The following kind of groups are supported:
51 #-# * LDAP static groups (users/subgroups are listed statically in the group object)
52 #-# * [Since 3.3M1] LDAP organization units (users/subgroups are sub object of the provided organization unit)
53 #-# * [Since 3.3M1] LDAP filter (users/groups are object found in a search with the provided filter)
54 # xwiki.authentication.ldap.user_group=cn=developers,ou=groups,o=MegaNova,c=US
55
56 #-# [Since 1.5RC1, XWikiLDAPAuthServiceImpl]
57 #-# Only users not member of the following group can authenticate.
58 #-# The following kind of groups are supported:
59 #-# * LDAP static groups (users/subgroups are listed statically in the group object)
60 #-# * [Since 3.3M1] LDAP organization units (users/subgroups are sub object of the provided organization unit)
61 #-# * [Since 3.3M1] LDAP filter (users/groups are object found in a search with the provided filter)
62 # xwiki.authentication.ldap.exclude_group=cn=admin,ou=groups,o=MegaNova,c=US
63
64 #-# Specifies the LDAP attribute containing the identifier to be used as the XWiki name
65 #-# The default is cn
66 # xwiki.authentication.ldap.UID_attr=cn
67
68 #-# [Since 1.5M1, XWikiLDAPAuthServiceImpl]
69 #-# The potential LDAP groups classes. Separated by commas.
70 # xwiki.authentication.ldap.group_classes=group,groupOfNames,groupOfUniqueNames,dynamicGroup,dynamicGroupAux,groupWiseDistributionList,posixGroup,apple-group
71
72 #-# [Since 1.5M1, XWikiLDAPAuthServiceImpl]
73 #-# The potential names of the LDAP groups fields containings the members. Separated by commas.
74 # xwiki.authentication.ldap.group_memberfields=member,uniqueMember,memberUid
75
76 #-# retrieve the following fields from LDAP and store them in the XWiki user object (xwiki-attribute=ldap-attribute)
77 xwiki.authentication.ldap.fields_mapping=last_name=sn,first_name=givenName,email=mail
78
79 #-# [Since 1.3M2, XWikiLDAPAuthServiceImpl]
80 #-# On every login update the mapped attributes from LDAP to XWiki otherwise this happens only once when the XWiki
81 #-# account is created.
82 #-# - 0: only when creating user
83 #-# - 1: at each authentication
84 #-# The default is 0
85 xwiki.authentication.ldap.update_user=1
86
87 #-# [Since 8.1M2, XWikiLDAPAuthServiceImpl]
88 #-# On every login update photo from LDAP to XWiki avatar otherwise photo will not be updated.
89 #-# - 0: never
90 #-# - 1: at each authentication
91 #-# The default is 0
92 # xwiki.authentication.ldap.update_photo=0
93
94 #-# [Since 8.1M2, XWikiLDAPAuthServiceImpl]
95 #-# Profile attachment name which will be used to save LDAP photo.
96 #-# The default is ldapPhoto
97 # xwiki.authentication.ldap.photo_attachment_name=ldapPhoto
98
99 #-# [Since 8.1M2, XWikiLDAPAuthServiceImpl]
100 #-# Specifies the LDAP attribute containing the binary photo
101 #-# The default is thumbnailPhoto
102 # xwiki.authentication.ldap.photo_attribute=thumbnailPhoto
103
104 #-# [Since 1.3M2, XWikiLDAPAuthServiceImpl]
105 #-# Maps XWiki groups to LDAP groups, separator is "|".
106 #-# The following kind of groups are supported:
107 #-# * LDAP static groups (users/subgroups are listed statically in the group object)
108 #-# * [Since 3.3M1] LDAP organization units (users/subgroups are sub object of the provided organization unit)
109 #-# * [Since 3.3M1] LDAP filter (users/groups are object found in a search with the provided filter),
110 #-# | character in the filter need to be escaped with backslash (\).
111 #-#
112 #-# Here is an example:
113 # xwiki.authentication.ldap.group_mapping=XWiki.XWikiAdminGroup=cn=AdminRole,ou=groups,o=domain,c=com|\
114 # XWiki.LDAPUsers=ou=groups,o=domain,c=com|\
115 # XWiki.Organisation=(cn=testers)
116
117 #-# [Since 1.3M2, XWikiLDAPAuthServiceImpl]
118 #-# Time in s after which the list of members in a group is refreshed from LDAP
119 #-# The default is 21600 (6 hours)
120 # xwiki.authentication.ldap.groupcache_expiration=21600
121
122 #-# [Since 1.3M2, XWikiLDAPAuthServiceImpl]
123 #-# - create : synchronize group membership only when the user is first created
124 #-# - always: synchronize on every login
125 #-# The default is always
126 # xwiki.authentication.ldap.mode_group_sync=always
127
128 #-# [Since 7.2M3, XWikiLDAPAuthServiceImpl]
129 #-# Indicate groups members should be resolved in case they are subgroups.
130 #-# Doing so can be very expensive so it should be disabled if you know there is no subgroups
131 #-# (or if you don't care about them).
132 #-# If the group is actually a filter it will always be resolved since it does not make sense left alone.
133 #-# - 0: disable
134 #-# - 1: enable
135 #-# The default is 1
136 # xwiki.authentication.ldap.group_sync_resolve_subgroups=0
137
138 #-# [Since 1.3M2, XWikiLDAPAuthServiceImpl]
139 #-# If ldap authentication fails for any reason, try XWiki DB authentication with the same credentials
140 #-# - 0: disable
141 #-# - 1: enable
142 #-# The default is 0
143 xwiki.authentication.ldap.trylocal=1
144
145 #-# [Since 1.3M2, XWikiLDAPAuthServiceImpl]
146 #-# SSL connection to LDAP server
147 #-# - 0: normal
148 #-# - 1: SSL
149 #-# The default is 0
150 # xwiki.authentication.ldap.ssl=0
151
152 #-# [Since 1.3M2, XWikiLDAPAuthServiceImpl]
153 #-# The keystore file to use in SSL connection
154 # xwiki.authentication.ldap.ssl.keystore=
155
156 #-# [Since 1.5M1, XWikiLDAPAuthServiceImpl]
157 #-# The java secure provider used in SSL connection
158 #-# The default is com.sun.net.ssl.internal.ssl.Provider
159 # xwiki.authentication.ldap.ssl.secure_provider=com.sun.net.ssl.internal.ssl.Provider
160
161 #-# Bypass standard LDAP bind validation by doing a direct password comparison.
162 #-# If you don't know what you do, don't use that. It's covering very rare and bad use cases.
163 #-# - 0: disable
164 #-# - 1: enable
165 #-# The default is 0
166 # xwiki.authentication.ldap.validate_password=0
167
168 #-# [Since 1.5M1, XWikiLDAPAuthServiceImpl]
169 #-# Specifies the LDAP attribute containing the password to be used "when xwiki.authentication.ldap.validate_password"
170 #-# is set to 1
171 # xwiki.authentication.ldap.password_field=userPassword
172
173 #-# [Since 4.3M1, XWikiLDAPAuthServiceImpl]
174 #-# The maximum number of milliseconds the client waits for any operation under these constraints to complete.
175 #-# The default is 1000
176 # xwiki.authentication.ldap.timeout=1000
177
178 #-# [Since 6.3M1, XWikiLDAPAuthServiceImpl]
179 #-# The maximum number of search results to be returned from a search operation.
180 #-# The default is 1000
181 # xwiki.authentication.ldap.maxresults=1000
182 {{/code}}
183
184 {{info}}
185 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##.
186 {{/info}}
187
188 == LDAP clients ==
189
190 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.
191
192 Here are some LDAP clients for checking your configuration:
193
194 Extensions:
195
196 * [[LDAP query snippet>>snippets:Extension.LDAP Query]]
197
198 Java based and Open Source:
199
200 * [[Apache Directory Studio>>http://directory.apache.org/studio/]]
201 * [[JXplorer>>http://jxplorer.org/]]
202
203 Windows only:
204
205 * [[Softerra LDAP Browser>>http://www.ldapbrowser.com/info_softerra-ldap-browser.htm]]
206
207 == Detailed use cases ==
208
209 See the [[LDAP configuration uses cases>>Documentation.AdminGuide.LDAPAuthenticationUseCases]] for some detailed use cases.
210
211 == Enable LDAP debug log ==
212
213 See [[Documentation.AdminGuide.Logging]].
214
215 The specific packages to track for LDAP are ##com.xpn.xwiki.plugin.ldap## and ##com.xpn.xwiki.user.impl.LDAP##.
216
217 Starting with XWiki 4.2 we added a new [[Logging UI>>extensions:Extension.Logging Application]] from the Administration section, which allows logging to be enabled at runtime, directly from the UI, without the need to restart the wiki.
218
219 In XWiki 3.4 you need to add the following in ##WEB-INF/classes/logback.xml##:
220
221 {{code}}
222 <!-- LDAP debugging -->
223 <logger name="com.xpn.xwiki.plugin.ldap" level="trace"/>
224 <logger name="com.xpn.xwiki.user.impl.LDAP" level="trace"/>
225 {{/code}}
226
227 Before 3.1, add the following to the log4j configuration file:
228
229 {{code}}
230 log4j.logger.com.xpn.xwiki.plugin.ldap=trace
231 log4j.logger.com.xpn.xwiki.user.impl.LDAP=trace
232 {{/code}}

Get Connected