Hide last authors
Manuel Smeria 31.2 1 Here you can find some detailed uses cases of LDAP authentication configuration:
Thomas Mortagne 1.1 2
Manuel Smeria 31.2 3 {{toc/}}
Thomas Mortagne 1.1 4
Manuel Smeria 31.2 5 = Active Directory =
Thomas Mortagne 4.1 6
Alex Cotiugă 44.1 7 {{info}}
Alex Cotiugă 45.1 8 If you're interested in connecting XWiki with Active Directory you may be interested in the [[Active Directory Application>>https://store.xwiki.com/xwiki/bin/view/Extension/ActiveDirectoryApplication]], which is a paying application dedicated to simplifying the integration of Active Directory with XWiki.
Alex Cotiugă 44.1 9 {{/info}}
10
Manuel Smeria 31.3 11 Here are the values of the properties you need to set if your LDAP server implementation is Microsoft Active Directory:
Thomas Mortagne 23.1 12
Manuel Smeria 31.1 13 * **ldap_server**: name/IP of AD server machine
14 * **ldap_port**: port //(e.g. 389)//
15 * **ldap_base_DN**: name of root DN //(e.g. dc=ad,dc=company,dc=com)//
Thomas Mortagne 47.1 16 * **ldap_bind_DN**: domain\{0} //(e.g. ad{0} where {0} will be replaced by username during validation)//
Manuel Smeria 31.1 17 * **ldap_bind_pass**: {1} //(where {1} will be replaced by password during validation)//
18 * **ldap_UID_attr**: sAMAccountName
19 * **ldap_fields_mapping**: name=sAMAccountName,last_name=sn,first_name=givenName,fullname=displayName,email=mail,ldap_dn=dn
20
Thomas Mortagne 23.1 21 Example:
Manuel Smeria 31.1 22
23 {{code}}
Thomas Mortagne 23.1 24 xwiki.authentication.ldap.server=adserver
25 xwiki.authentication.ldap.port=389
26 xwiki.authentication.ldap.base_DN=dc=subdomain,dc=domain,dc=suffix
27 xwiki.authentication.ldap.bind_DN=subdomain\\{0}
28 xwiki.authentication.ldap.bind_pass={1}
29 xwiki.authentication.ldap.UID_attr=sAMAccountName
30 xwiki.authentication.ldap.fields_mapping=name=sAMAccountName,last_name=sn,first_name=givenName,fullname=displayName,email=mail,ldap_dn=dn
Manuel Smeria 31.1 31 {{/code}}
Thomas Mortagne 23.1 32
Manuel Smeria 31.2 33 = Apple Open Directory Server =
Thomas Mortagne 23.1 34
Manuel Smeria 31.3 35 In order to set this up your **xwiki.cfg** file should have the attributes below set like this:
Thomas Mortagne 23.1 36
Manuel Smeria 31.1 37 {{code}}
Thomas Mortagne 23.1 38 xwiki.authentication.ldap.bind_DN=uid={0},cn=users,dc=sub,dc=domain,dc=tld
39 xwiki.authentication.ldap.bind_pass={1}
40 xwiki.authentication.ldap.UID_attr=uid
41 xwiki.authentication.ldap.group_classes=apple-group
42 xwiki.authentication.ldap.group_memberfields=memberUid,uid
Manuel Smeria 31.1 43 {{/code}}
Thomas Mortagne 23.1 44
Manuel Smeria 31.3 45 Note that if you set it up like this the users logging will need the right to list group members in LDAP server.
Thomas Mortagne 23.1 46
Manuel Smeria 31.2 47 = Open Directory Server (OpenDS) =
David Hymonnet 26.1 48
Manuel Smeria 31.3 49 Here are the values of the properties you need to set if you would like to **authorize only members of a group to log-in**. In this case, the group is cn=xwiki,ou=roles,dc=domain,dc=tld
David Hymonnet 26.1 50
Manuel Smeria 31.1 51 {{code}}
David Hymonnet 26.1 52 xwiki.authentication.ldap.server=ldap.domain.tld
53 xwiki.authentication.ldap.port=389
David Hymonnet 27.1 54
David Hymonnet 26.1 55 xwiki.authentication.ldap.bind_DN=
56 xwiki.authentication.ldap.bind_pass=
David Hymonnet 27.1 57
David Hymonnet 26.1 58 xwiki.authentication.ldap.base_DN=ou=people,dc=domain,dc=tld
59 xwiki.authentication.ldap.UID_attr=cn
David Hymonnet 27.1 60
David Hymonnet 26.1 61 xwiki.authentication.ldap.group_classes=groupOfNames
62 xwiki.authentication.ldap.group_memberfields=memberUid
David Hymonnet 27.1 63 xwiki.authentication.ldap.user_group=cn=xwiki,ou=roles,dc=domain,dc=tld
Manuel Smeria 31.1 64 {{/code}}
David Hymonnet 26.1 65
Manuel Smeria 31.3 66 **bind_DN** and **bind_pass** are both empty. The connection to the LDAP server will be anonymous. With OpenDS an anonymous connection can read some needed attributes like userPassword, home, etc.
David Hymonnet 27.2 67
Manuel Smeria 31.2 68 = Generic =
Thomas Mortagne 23.1 69
Thomas Mortagne 38.1 70 == I want to have LDAP on ##subwiki1## but not on ##subwiki2## ==
Thomas Mortagne 35.1 71
72 Each wiki can have it's own LDAP setup. When LDAP fail on a subwiki it fallback on main wiki.
73
74 Two possibilities:
75
Thomas Mortagne 38.1 76 === Disable LDAP by default for all wikis and then enable it only in wikis where you want it ===
Thomas Mortagne 35.1 77
78 * disable LDAP at xwiki.cfg level (which is the default configuration for all wikis)(((
79 {{code language="properties"}}
80 xwiki.authentication.ldap=0
Thomas Mortagne 38.1 81 {{/code}}
Pascal Bastien 43.2 82 )))*enable it only in subwikis where we want it: can be done by directly editing XWiki.XWikiReference document with object editor (http://ldapwiki.mydomain.org/xwiki/bin/edit/XWiki/XWikiPreferences?editor=objet) or using [[LDAP Application>>extensions:Extension.LDAP.Application]].
Thomas Mortagne 35.1 83
Thomas Mortagne 38.1 84 === Enable LDAP by default for all wikis and then disable it only on wikis where you don't want it ===
Thomas Mortagne 35.1 85
86 * enable LDAP at xwiki.cfg level (which is the default configuration for all wikis)(((
87 {{code language="properties"}}
88 xwiki.authentication.ldap=1
Thomas Mortagne 38.1 89 {{/code}}
90 )))
Pascal Bastien 43.2 91 * disable it only in subwikis where we want it: can be done by directly editing XWiki.XWikiReference document with object editor (http://ldapwiki.mydomain.org/xwiki/bin/edit/XWiki/XWikiPreferences?editor=objet) or using [[LDAP Application>>extensions:Extension.LDAP.Application]].
Thomas Mortagne 35.1 92
93 {{warning}}
94 Righs now the authenticator always fallback on main wiki when LDAP is disabled or does not work on subwiki. That mean it's not possible to have LDAP auth working when logging in from main wiki but and failing when logging in from a subwiki. In such a case you will be logged with a global user (main wiki user), same as if you were accessing main wiki and then subwiki in the same session.
95
96 But what you can do in this case is to not allow main wiki users from accessing the subwiki which will essentially have the same result.
97 {{/warning}}
98
Manuel Smeria 31.2 99 == I want to be able to reuse LDAP users membership in XWiki ==
Thomas Mortagne 8.1 100
Manuel Smeria 31.3 101 E.g. if you want all the LDAP users of the group ##cn=HMS Lydia,ou=crews,ou=groups,o=sevenSeas## to be automatically added in the XWiki group ##XWiki.XWikiAdminGroup## when the user logs in, set:
Manuel Smeria 31.1 102
103 {{code}}
Thomas Mortagne 8.1 104 xwiki.authentication.ldap.group_mapping=XWiki.XWikiAdminGroup=cn=HMS Lydia,ou=crews,ou=groups,o=sevenSeas
Manuel Smeria 31.1 105 {{/code}}
Thomas Mortagne 8.1 106
Manuel Smeria 31.3 107 If you want to add more mapping add them separated by ##|##:
Manuel Smeria 31.1 108
109 {{code}}
Thomas Mortagne 8.1 110 xwiki.authentication.ldap.group_mapping=XWiki.XWikiAdminGroup=cn=HMS Lydia,ou=crews,ou=groups,o=sevenSeas|\
111 XWiki.OtherXWikiGroup=HMS Victory,ou=crews,ou=groups,o=sevenSeas
Manuel Smeria 31.1 112 {{/code}}
Thomas Mortagne 8.1 113
Manuel Smeria 31.2 114 == My users are not located in the same organization unit ==
Thomas Mortagne 4.1 115
Manuel Smeria 31.1 116 So you can't use the ##xwiki.authentication.ldap.bind_DN=cn={0},department=USER,department=INFORMATIK,department=1230,o=MP## pattern.
Thomas Mortagne 4.1 117
Thomas Mortagne 22.1 118 The trick here is to to connect to LDAP with a user able to list LDAP users (and groups if you want to do membership synchronization).
Thomas Mortagne 21.1 119
Manuel Smeria 31.3 120 To handle that LDAP authentication automatically searches for the user's DN trying to match the provided login with ##xwiki.authentication.ldap.UID_attr## attribute value. So simply set an existing administrator DN (or any other LDAP user with the right to search in the whole LDAP server) at ##xwiki.authentication.ldap.bind_DN## and its password at ##xwiki.authentication.ldap.bind_pass##. LDAP authentication will use it to connect to the LDAP server, search for the provided user and bind the found DN with the provided password to validate it.
Thomas Mortagne 4.1 121
Manuel Smeria 31.3 122 For example if you have an admin user with the DN = "cn=Administrator,dc=mydomain,dc=org" and password "pass" set:
Manuel Smeria 31.1 123
124 {{code}}
Thomas Mortagne 4.1 125 xwiki.authentication.ldap.bind_DN=cn=Administrator,dc=mydomain,dc=org
126 xwiki.authentication.ldap.bind_pass=pass
Manuel Smeria 31.1 127 {{/code}}
steel 5.1 128
Manuel Smeria 31.2 129 == My users are not located on the same server ==
steel 5.1 130
Manuel Smeria 31.3 131 E.g. if you use several subdomains and the users are defined separately in each subdomain. This will likely be the case when you have a configuration like this:
steel 5.1 132
Manuel Smeria 31.1 133 {{code}}
steel 5.1 134 sub1.somedomain.com
135 sub2.somedomain.com
136 sub3.somedomain.com
137 ...
Manuel Smeria 31.1 138 {{/code}}
steel 5.1 139
Thomas Mortagne 46.1 140 === Approach 1: Let the user indicate the domain ===
steel 5.1 141
Thomas Mortagne 46.1 142 Since 9.0 it's possible to map a different configuration for each in the xwiki.cfg file by playing with the ##xwiki.authentication.ldap.remoteUser*## properties.
steel 5.1 143
Thomas Mortagne 46.1 144 Then instead of typing {{code language="none"}}myuid{{/code}} the user will login using something like {{code language="none"}}[email protected]{{/code}} so that the LDAP authenticator kind find the right server setup based on the provided domain.
145
146 === Approach 2: Configure group membership login ===
147
Manuel Smeria 31.3 148 One possible solution is to make one (or more) group(s) in your AD and set the group membership to all users that have to have access to your wiki. Then configure XWiki to only let members of that group log in. If a user wants to log in, XWiki will look up if the user's credentials are found in the group member attributes in AD. With this setting, XWiki will ignore the base_DN search, if a user was found in that group.
steel 6.1 149
Manuel Smeria 31.3 150 {{info}}
151 The group membership attribute in AD (in its default configuration) will contain the CN ("FirstName LastName") - not the sAMAccountName. So your users will have to login with their full name instead of their username.
152 {{/info}}
Thomas Mortagne 15.1 153
Manuel Smeria 31.3 154 == I'm in a multiwiki environment and I want my LDAP users to register only on the main wiki ==
Thomas Mortagne 15.1 155
Thomas Mortagne 42.1 156 Each wiki can have its own LDAP configuration (even enable/disable LDAP) in the ##XWiki.XWikiPreference## page or using the [[LDAP Application>>Extension.LDAP.Application]]. What you can find in the ##xwiki.cfg## configuration file is just the default LDAP configuration and it can be overridden in subwikis.
Thomas Mortagne 17.1 157
Manuel Smeria 31.3 158 When the LDAP authenticator fails to authenticate to a wiki it will try in the main wiki.
Manuel Smeria 31.1 159
Manuel Smeria 31.3 160 In order to forbid LDAP authentication to create users on subwikis you can use one of the following ways:
Manuel Smeria 31.1 161
Thomas Mortagne 42.1 162 * disable LDAP in **xwiki.cfg** and enable it in the main wiki by choosing "Yes" for the "LDAP" field
Eduard Moraru 45.2 163 * enable LDAP in **xwiki.cfg** and disable it in every sub-wikis that are not allowed to create users by choosing "No" in the "LDAP"
Jeremie Grauer 30.1 164
Manuel Smeria 31.2 165 == I want to allow access to users depending on a specific attribute on their LDAP entry ==
Jeremie Grauer 30.1 166
167 For example, suppose you want to prevent access to the wiki for deactivated users, and you have an attribute in LDAP showing the current status of the user.
168
169 Typically, you may have this kind of attribute:
170
Manuel Smeria 31.1 171 * For Zimbra based LDAP, an active account has this attribute: **zimbraAccountStatus=active**
172 * For ActiveDirectory, a deactivated account has this attribute: **userAccountControl:1.2.840.113556.1.4.803:=2**
173 * Or you can have your own attribute in your private schema, for example: **accountstatus=active**
174
Manuel Smeria 31.3 175 In this case, you just have to modify the **xwiki.authentication.ldap.user_group** value by putting the filter corresponding to what you want. Using the same example as above, you'll have:
Jeremie Grauer 30.1 176
jean coury 33.1 177 * For Zimbra based LDAP:(((
Manuel Smeria 31.1 178 {{code}}
179 xwiki.authentication.ldap.user_group=(zimbraAccountStatus=active)
180 {{/code}}
Manuel Smeria 31.3 181 )))
jean coury 33.1 182 * For ActiveDirectory:(((
Manuel Smeria 31.1 183 {{code}}
184 xwiki.authentication.ldap.user_group=(!(userAccountControl:1.2.840.113556.1.4.803:=2))
185 {{/code}}
Manuel Smeria 31.3 186 )))
jean coury 33.1 187 * For a private attribute:(((
Manuel Smeria 31.1 188 {{code}}
189 xwiki.authentication.ldap.user_group=(accountstatus=active)
190 {{/code}}
Manuel Smeria 31.3 191 )))
Manuel Smeria 31.1 192
Manuel Smeria 31.3 193 You can of course use any kind of filter. For instance, you can check if the account is active and has any other attribute, like an attribute listing the different services the user can access:
Manuel Smeria 31.1 194
195 {{code}}
196 xwiki.authentication.ldap.user_group=(&(accountstatus=active)(allowedservice=xwiki))
197 {{/code}}
Pascal Bastien 37.1 198
199 == Use LDAP over SSL (ldaps authentication) ==
Thomas Mortagne 38.1 200
Pascal Bastien 37.1 201 To adds support for SSL connections to the ldap server you need:
Thomas Mortagne 38.1 202
Pascal Bastien 37.1 203 * to set (xwiki.authentication.ldap.ssl) parameter in xwiki.cfg(((
204 {{code language="properties"}}
205 #-# SSL connection to LDAP server
206 #-# - 0: normal
207 #-# - 1: SSL
208 #-# The default is 0
209 xwiki.authentication.ldap.ssl=1
Thomas Mortagne 38.1 210 {{/code}}
211 )))
Pascal Bastien 37.1 212 * and add to the trust store of the JSSE extension the CA certificate which delivered the SSL certificate of the ldap server.(((
213 From the Sun JSSE documentation: The search order for the locating the trust store is:
Thomas Mortagne 38.1 214
Thomas Mortagne 41.1 215 1. ##<java-home>/lib/security/jssecacerts, then##
216 1. ##<java-home>/lib/security/cacerts##
Pascal Bastien 37.1 217 If the file jssecacerts exists, then cacerts is not consulted. So in order to make it work you have to create a trust store named jssecacerts with the following command and place it in the suitable directory of the JRE or JDK used by your container:
Thomas Mortagne 38.1 218 {{code}}keytool -import -trustcacerts -alias ca -file cacert.crt -keystore jssecacerts{{/code}}
Pascal Bastien 37.1 219 (answer yes when asked if you want to trust the certificate). I read on the web the default password for cacerts is 'changeit' so I used that, I didn't try yet with another password for the trust store.
Pascal Bastien 41.2 220 Since xwiki 8.3, the default extension repositories use httpS and if the file jssecacerts already exists (ie for ldapS in xwiki previous version) then cacerts is not consulted and extension update (and probably install too) display an error: //unable to find valid certification path to requested target//.
Pascal Bastien 37.1 221 The problem is:
Thomas Mortagne 38.1 222
Pascal Bastien 37.1 223 * cacerts containing all certificate/keys (and the one for httpS extension repositories)
Thomas Mortagne 39.1 224 * (((
225 jssecacerts containing only ldapS certificate
Pascal Bastien 37.1 226 Then, to use ldapS and extension update, you must import ldapS certicate in existent cacerts file instead to create a new one (and rename it in jssecacerts to not forget it)
Thomas Mortagne 39.1 227
228 {{code language="bash"}}
229 cp <java-home>/lib/security/cacerts <java-home>/jre/lib/security/cacerts.ori
Pascal Bastien 37.1 230 <java-home>/bin/keytool -import -trustcacerts -alias ca -file /my/path/ToLdapS/cert/MyLdapCertificate.pem -keystore <java-home>/lib/security/cacerts
231 mv <java-home>/lib/security/cacerts <java-home>/lib/security/jssecacerts
Thomas Mortagne 39.1 232 mv <java-home>/lib/security/cacerts.ori <java-home>/jre/lib/security/cacerts
233 {{/code}}
Pascal Bastien 37.1 234 )))
Thomas Mortagne 39.1 235 )))

Get Connected