Wiki source code of Old LDAP Authenticator
Last modified by Thomas Mortagne on 2018/02/09
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 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}} |
