Version 37.1 by Pascal Bastien on 2016/11/03 18:05

Show last authors
1 Here you can find some detailed uses cases of LDAP authentication configuration:
2
3 {{toc/}}
4
5 = Active Directory =
6
7 Here are the values of the properties you need to set if your LDAP server implementation is Microsoft Active Directory:
8
9 * **ldap_server**: name/IP of AD server machine
10 * **ldap_port**: port //(e.g. 389)//
11 * **ldap_base_DN**: name of root DN //(e.g. dc=ad,dc=company,dc=com)//
12 * **ldap_bind_DN**: domain{0} //(e.g. ad{0} where {0} will be replaced by username during validation)//
13 * **ldap_bind_pass**: {1} //(where {1} will be replaced by password during validation)//
14 * **ldap_UID_attr**: sAMAccountName
15 * **ldap_fields_mapping**: name=sAMAccountName,last_name=sn,first_name=givenName,fullname=displayName,email=mail,ldap_dn=dn
16
17 Example:
18
19 {{code}}
20 xwiki.authentication.ldap.server=adserver
21 xwiki.authentication.ldap.port=389
22 xwiki.authentication.ldap.base_DN=dc=subdomain,dc=domain,dc=suffix
23 xwiki.authentication.ldap.bind_DN=subdomain\\{0}
24 xwiki.authentication.ldap.bind_pass={1}
25 xwiki.authentication.ldap.UID_attr=sAMAccountName
26 xwiki.authentication.ldap.fields_mapping=name=sAMAccountName,last_name=sn,first_name=givenName,fullname=displayName,email=mail,ldap_dn=dn
27 {{/code}}
28
29 = Apple Open Directory Server =
30
31 In order to set this up your **xwiki.cfg** file should have the attributes below set like this:
32
33 {{code}}
34 xwiki.authentication.ldap.bind_DN=uid={0},cn=users,dc=sub,dc=domain,dc=tld
35 xwiki.authentication.ldap.bind_pass={1}
36 xwiki.authentication.ldap.UID_attr=uid
37 xwiki.authentication.ldap.group_classes=apple-group
38 xwiki.authentication.ldap.group_memberfields=memberUid,uid
39 {{/code}}
40
41 Note that if you set it up like this the users logging will need the right to list group members in LDAP server.
42
43 = Open Directory Server (OpenDS) =
44
45 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
46
47 {{code}}
48 xwiki.authentication.ldap.server=ldap.domain.tld
49 xwiki.authentication.ldap.port=389
50
51 xwiki.authentication.ldap.bind_DN=
52 xwiki.authentication.ldap.bind_pass=
53
54 xwiki.authentication.ldap.base_DN=ou=people,dc=domain,dc=tld
55 xwiki.authentication.ldap.UID_attr=cn
56
57 xwiki.authentication.ldap.group_classes=groupOfNames
58 xwiki.authentication.ldap.group_memberfields=memberUid
59 xwiki.authentication.ldap.user_group=cn=xwiki,ou=roles,dc=domain,dc=tld
60 {{/code}}
61
62 **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.
63
64 = Generic =
65
66 == I want to have LDAP on ##subwiki1## but not on ##subwiki2##
67
68 Each wiki can have it's own LDAP setup. When LDAP fail on a subwiki it fallback on main wiki.
69
70 Two possibilities:
71
72 === Disable LDAP by default for all wikis and then enable it only in wikis where you want it
73
74 * disable LDAP at xwiki.cfg level (which is the default configuration for all wikis)(((
75 {{code language="properties"}}
76 xwiki.authentication.ldap=0
77 {{/code}})))
78 *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 [[extensions:Extension.LDAP Application]].
79
80 === Enable LDAP by default for all wikis and then disable it only on wikis where you don't want it
81
82 * enable LDAP at xwiki.cfg level (which is the default configuration for all wikis)(((
83 {{code language="properties"}}
84 xwiki.authentication.ldap=1
85 {{/code}})))
86 * 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 [[extensions:Extension.LDAP Application]].
87
88 {{warning}}
89 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.
90
91 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.
92 {{/warning}}
93
94 == I want to be able to reuse LDAP users membership in XWiki ==
95
96 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:
97
98 {{code}}
99 xwiki.authentication.ldap.group_mapping=XWiki.XWikiAdminGroup=cn=HMS Lydia,ou=crews,ou=groups,o=sevenSeas
100 {{/code}}
101
102 If you want to add more mapping add them separated by ##|##:
103
104 {{code}}
105 xwiki.authentication.ldap.group_mapping=XWiki.XWikiAdminGroup=cn=HMS Lydia,ou=crews,ou=groups,o=sevenSeas|\
106 XWiki.OtherXWikiGroup=HMS Victory,ou=crews,ou=groups,o=sevenSeas
107 {{/code}}
108
109 == My users are not located in the same organization unit ==
110
111 So you can't use the ##xwiki.authentication.ldap.bind_DN=cn={0},department=USER,department=INFORMATIK,department=1230,o=MP## pattern.
112
113 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).
114
115 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.
116
117 For example if you have an admin user with the DN = "cn=Administrator,dc=mydomain,dc=org" and password "pass" set:
118
119 {{code}}
120 xwiki.authentication.ldap.bind_DN=cn=Administrator,dc=mydomain,dc=org
121 xwiki.authentication.ldap.bind_pass=pass
122 {{/code}}
123
124 == My users are not located on the same server ==
125
126 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:
127
128 {{code}}
129 sub1.somedomain.com
130 sub2.somedomain.com
131 sub3.somedomain.com
132 ...
133 {{/code}}
134
135 XWiki cannot search in multiple domains (as of XWiki 1.5).
136
137 === Approach 1: Configure group membership login ===
138
139 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.
140
141 {{info}}
142 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.
143 {{/info}}
144
145 == I'm in a multiwiki environment and I want my LDAP users to register only on the main wiki ==
146
147 Each wiki can have its own LDAP configuration (even enable/disable LDAP) in the ##XWiki.XWikiPreference## page (edit it in [[objects mode>>platform:Features.PageEditing||anchor="HAdvancedMode"]]. See [[How to navigate to a page>>xwiki:FAQ.How can I navigate to a given page]]). What you can find in the ##xwiki.cfg## configuration file is just the default LDAP configuration and it can be overridden in subwikis.
148
149 When the LDAP authenticator fails to authenticate to a wiki it will try in the main wiki.
150
151 In order to forbid LDAP authentication to create users on subwikis you can use one of the following ways:
152
153 * disable LDAP in **xwiki.cfg** and enable it in the main wiki by choosing "Yes" in the "Ldap" field of ##XWiki.XWikiPreference## page object
154 * disable LDAP in every sub-wikis by choosing "No" in the "Ldap" field of ##XWiki.XWikiPreference## page object
155
156 == I want to allow access to users depending on a specific attribute on their LDAP entry ==
157
158 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.
159
160 Typically, you may have this kind of attribute:
161
162 * For Zimbra based LDAP, an active account has this attribute: **zimbraAccountStatus=active**
163 * For ActiveDirectory, a deactivated account has this attribute: **userAccountControl:1.2.840.113556.1.4.803:=2**
164 * Or you can have your own attribute in your private schema, for example: **accountstatus=active**
165
166 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:
167
168 * For Zimbra based LDAP:(((
169 {{code}}
170 xwiki.authentication.ldap.user_group=(zimbraAccountStatus=active)
171 {{/code}}
172 )))
173 * For ActiveDirectory:(((
174 {{code}}
175 xwiki.authentication.ldap.user_group=(!(userAccountControl:1.2.840.113556.1.4.803:=2))
176 {{/code}}
177 )))
178 * For a private attribute:(((
179 {{code}}
180 xwiki.authentication.ldap.user_group=(accountstatus=active)
181 {{/code}}
182 )))
183
184 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:
185
186 {{code}}
187 xwiki.authentication.ldap.user_group=(&(accountstatus=active)(allowedservice=xwiki))
188 {{/code}}
189
190 == Use LDAP over SSL (ldaps authentication) ==
191 To adds support for SSL connections to the ldap server you need:
192 * to set (xwiki.authentication.ldap.ssl) parameter in xwiki.cfg(((
193 {{code language="properties"}}
194 #-# SSL connection to LDAP server
195 #-# - 0: normal
196 #-# - 1: SSL
197 #-# The default is 0
198 xwiki.authentication.ldap.ssl=1
199 {{/code}})))
200 * and add to the trust store of the JSSE extension the CA certificate which delivered the SSL certificate of the ldap server.(((
201 From the Sun JSSE documentation: The search order for the locating the trust store is:
202 1. <java-home>/lib/security/jssecacerts, then
203 1. <java-home>/lib/security/cacerts
204 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:
205 {{code}}
206 keytool -import -trustcacerts -alias ca -file cacert.crt -keystore jssecacerts
207 {{/code}}
208 (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.
209 Since xwiki 8.3, the default extension repositories use httpS and if the file jssecacerts exists (here fore ldapS) then cacerts is not consulted and extension update (and probably install too) display an error: //unable to find valid certification path to requested target//.
210 The problem is:
211 * cacerts containing all certificate/keys (and the one for httpS extension repositories)
212 * jssecacerts containing only ldapS certificate
213 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)
214 {{code}}
215 cp <java-home>/lib/security/cacerts <java-home>/jre/lib/security/cacerts.ori
216 <java-home>/bin/keytool -import -trustcacerts -alias ca -file /my/path/ToLdapS/cert/MyLdapCertificate.pem -keystore <java-home>/lib/security/cacerts
217 mv <java-home>/lib/security/cacerts <java-home>/lib/security/jssecacerts
218 mv <java-home>/lib/security/cacerts.ori <java-home>/jre/lib/security/cacerts
219 {{/code}}
220 )))
221 (Source: http://jira.xwiki.org/browse/XWIKI-865)

Get Connected