Skip to Content

Wiki source code of User Authentication

Version 36.1 by Thomas Mortagne on 2010/04/19
Show last authors
1 XWiki supports several different authentication mechanisms for authenticating users:
2
3 {{toc/}}
4
5 The form authentication is the default mechanism.
6
7 {{info}}
8 Note that currently XWiki allows only one method of authentication to be enabled at a time. This will probably be improved in the future.
9 {{/info}}
10
11 = Form Authentication =
12
13 TODO
14
15 = LDAP Authentication =
16
17 {{warning}}
18 New LDAP implementation since XWiki Platform 1.3M2, see [[previous LDAP authentication service documentation>>AuthenticationLdapOld]]
19 {{/warning}}
20
21 == Generic LDAP configuration ==
22
23 In order to enable the LDAP support you have to change the authentication method in //WEB-INF/xwiki.cfg// as follows:
24
25 {{code}}
26 ## Turn LDAP authentication on - otherwise only XWiki authentication
27 ## 0 : disable
28 ## 1 : enable
29 xwiki.authentication.ldap=1
30
31 ## set LDAP as authentication service
32 xwiki.authentication.authclass=com.xpn.xwiki.user.impl.LDAP.XWikiLDAPAuthServiceImpl
33 {{/code}}
34
35 You can setup the LDAP configuration in the //xwiki.cfg// file by filling the following properties:
36
37 {{code language="none"}}
38 #-# LDAP Server (Active Directory, eDirectory, OpenLDAP, etc.)
39 xwiki.authentication.ldap.server=127.0.0.1
40 xwiki.authentication.ldap.port=389
41
42 #-# LDAP login, empty = anonymous access, otherwise specify full dn
43 #-# {0} is replaced with the username, {1} with the password
44 xwiki.authentication.ldap.bind_DN=cn={0},department=USER,department=INFORMATIK,department=1230,o=MP
45 xwiki.authentication.ldap.bind_pass={1}
46
47 #-# Force to check password after LDAP connection
48 #-# 0: disable
49 #-# 1: enable
50 xwiki.authentication.ldap.validate_password=0
51
52 #-# only members of the following group will be verified in the LDAP
53 #-# otherwise only users that are found after searching starting from the base_DN
54 # xwiki.authentication.ldap.user_group=cn=developers,ou=groups,o=MegaNova,c=US
55
56 #-# only users not member of the following group can autheticate
57 # xwiki.authentication.ldap.exclude_group=cn=admin,ou=groups,o=MegaNova,c=US
58
59 #-# base DN for searches
60 xwiki.authentication.ldap.base_DN=
61
62 #-# Specifies the LDAP attribute containing the identifier to be used as the XWiki name (default=cn)
63 # xwiki.authentication.ldap.UID_attr=cn
64
65 #-# Specifies the LDAP attribute containing the password to be used "when xwiki.authentication.ldap.validate_password" is set to 1
66 # xwiki.authentication.ldap.password_field=userPassword
67
68 #-# The potential LDAP groups classes. Separated by commas.
69 # xwiki.authentication.ldap.group_classes=group,groupOfNames,groupOfUniqueNames,dynamicGroup,dynamicGroupAux,groupWiseDistributionList
70
71 #-# The potential names of the LDAP groups fields containings the members. Separated by commas.
72 # xwiki.authentication.ldap.group_memberfields=member,uniqueMember
73
74 #-# retrieve the following fields from LDAP and store them in the XWiki user object (xwiki-attribute=ldap-attribute)
75 xwiki.authentication.ldap.fields_mapping=last_name=sn,first_name=givenName,email=mail
76
77 #-# on every login update the mapped attributes from LDAP to XWiki otherwise this happens only once when the XWiki account is created.
78 xwiki.authentication.ldap.update_user=1
79
80 #-# mapps XWiki groups to LDAP groups, separator is "|"
81 # xwiki.authentication.ldap.group_mapping=XWiki.XWikiAdminGroup=cn=AdminRole,ou=groups,o=MegaNova,c=US|\
82 # XWiki.Organisation=cn=testers,ou=groups,o=MegaNova,c=US
83
84 #-# time in s after which the list of members in a group is refreshed from LDAP (default=3600*6)
85 # xwiki.authentication.ldap.groupcache_expiration=21800
86
87 #-# - create : synchronize group membership only when the user is first created
88 #-# - always: synchronize on every login
89 # xwiki.authentication.ldap.mode_group_sync=always
90
91 #-# if ldap authentication fails for any reason, try XWiki DB authentication with the same credentials
92 xwiki.authentication.ldap.trylocal=1
93
94 #-# SSL connection to LDAP server
95 #-# 0: normal
96 #-# 1: SSL
97 # xwiki.authentication.ldap.ssl=0
98
99 #-# The keystore file to use in SSL connection
100 # xwiki.authentication.ldap.ssl.keystore=
101
102 #-# The java secure provider used in SSL connection
103 # xwiki.authentication.ldap.ssl.secure_provider=com.sun.net.ssl.internal.ssl.Provider
104 {{/code}}
105
106 {{info}}
107 You can also setup the LDAP configuration in XWiki.XWikiPreferences page by going to the object editor. Simply replace "xwiki.authentication.ldap." by "ldap_". For example ##xwiki.authentication.ldap.base_DN## becomes ##ldap_base_DN##
108 {{/info}}
109
110 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.
111
112 Here are some LDAP client for checking your configuration:
113
114 * [[Apache Directory Studio>>http://directory.apache.org/studio/]]
115 * [[LDAP Browser/Editor>>http://www-unix.mcs.anl.gov/gawor/ldap/]]
116
117 == Detailed use cases ==
118
119 See [[LDAP configuration uses cases>>LDAPAuthenticationUseCases]] for some detailed use cases.
120
121 == Enable LDAP debug log ==
122
123 See [[AdminGuide.Logging]]. The specific targets for LDAP authentication are:
124
125 {{code}}
126 log4j.logger.com.xpn.xwiki.plugin.ldap=debug
127 log4j.logger.com.xpn.xwiki.user.impl.LDAP=debug
128 {{/code}}
129
130 = eXo Authentication =
131
132 The eXo authentication is used automatically by adding/editing the //xwiki.exo=1// property in //WEB-INF/xwiki.cfg//.
133
134 = Custom Authentication =
135
136 This allows plugging to any existing authentication mechanism such as SiteMinder, etc. To configure a custom authentication do the following:
137
138 1. Implement the [[XWikiAuthService>>http://svn.xwiki.org/svnroot/xwiki/platform/core/trunk/xwiki-core/src/main/java/com/xpn/xwiki/user/api/XWikiAuthService.java]] interface.
139 1. Edit the //WEB-INF/xwiki.cfg// file and add a //xwiki.authentication.authclass// property pointing to your class. For example:
140
141 {{code}}
142 xwiki.authentication.authclass = com.acme.MyCustomAuthenticationService
143 {{/code}}
144
145 Here's a [[tutorial on implementing a custom authentication class for authenticating against Oracle's SSO>>http://bodez.wordpress.com/2008/10/15/xwiki-user-authentication-with-oracle-sso/]].
146
147 Note, that you also can implement own right management service by implementing [[XWikiRightService>>http://svn.xwiki.org/svnroot/xwiki/platform/core/trunk/xwiki-core/src/main/java/com/xpn/xwiki/user/api/XWikiRightService.java]] interface:
148
149 {{code}}
150 xwiki.authentication.rightsclass = com.acme.MyCustomRightsService
151 {{/code}}
152
153 and Group Service by implementing [[XWikiGroupService>>http://svn.xwiki.org/svnroot/xwiki/platform/core/trunk/xwiki-core/src/main/java/com/xpn/xwiki/user/api/XWikiGroupService.java]]:
154
155 {{code}}
156 xwiki.authentication.groupclass = com.acme.MyCustomGroupService
157 {{/code}}
158
159 == Custom Authentication using a Groovy script in a wiki page ==
160
161 Start by specifying you want to use the Groovy Authenticator:
162
163 {{code}}
164 xwiki.authentication.authclass = com.xpn.xwiki.user.impl.xwiki.GroovyAuthServiceImpl
165 {{/code}}
166
167 Then add another configuration parameter to specify in which wiki page the authenticator is:
168
169 {{code}}
170 xwiki.authentication.groovy.pagename = MySpace.MyPage
171 {{/code}}
172
173 Then in a wiki page put some Groovy code that returns a XWikiAuthService object.
174
175 = Authentication parameters ===
176
177 You can set each of these parameters by setting:
178
179 {{code}}
180 xwiki.authentication.~~param_name~~=~~param_value~~
181 {{/code}}
182
183 |=Name|=Optional|=Allowed values|=Default value|=Description
184 |encryptionKey|No(1)|?|n/a|Set the Encryption Key used to create a secret key, the secret key is passed to the Cipher object to be used during encryption and decryption of cookie values.
185 |validationKey|No(2)|?|n/a|Set the Validation Key used to generate hash value; the hash value is stored with the cookie and used to verify that the cookie has not been tampered with.
186 |cookiedomains|Yes|String|Server host name|Which host(s) should your cookies be sent to; use only if you want to share cookies across domains, otherwise should be commented out
187 |cookielife|Yes|Number|14|Number of days cookies take to expire
188 |cookiepath|Yes|String|/|The webapp path that XWiki cookies should be sent to; if you have anything else running on your web server, this should be set to ///xwiki//
189 |default_page|Yes|String|/bin/view/ Main/WebHome|Page to redirect to if xredirect parameter is not set
190 |encryptionalgorithm|Yes|?|?|Set the Encryption Algorithm used to encrypt and decrypt cookies
191 |encryptionmode|Yes|?|?|Set the Encryption Mode used to encrypt and decrypt cookies
192 |encryptionpadding|Yes|?|?|Set the Encryption Padding used to encrypt and decrypt cookies
193 |errorpage|Yes|String|/bin/loginerror/ XWiki/XWikiLogin|Page to redirect to if there is an error logging in
194 |loginpage|Yes|String|/bin/login/ XWiki/XWikiLogin|Page to redirect to when not logged in
195 |loginsubmitpage|Yes|String|/loginsubmit/ XWiki/XWikiLogin|The URL where the username and password are posted to when logging in.
196 |logoutpage|Yes|String|/bin/logout/ XWiki/XWikiLogout|Page to redirect to after logged out
197 |realmname|Yes|String|XWiki|Sets the realm name
198 |protection|Yes|all, validation, encryption, none|all|Protection level for the "remember me" cookie functionality
199 |unauthorized_code|Yes|Number|401|The HTTP status code to return when the login has failed.
200 |useip|Yes|true / false|true|Specify to use the IP address when encrypting the cookie data; if IP address changes will need to re-login.
201
202 1. Only required if protection = encryption or all (default)
203 1. Only required if protection = validation or all (default)
204
205 = Kerberos SSO Authentication =
206
207 {{warning}}
208 This implementation of SSO is currently under review see: http://jira.xwiki.org/jira/browse/XWIKI-2496 . The class which is described in this segment of documentation, AppServerTrustedKerberosAuthServiceImpl, is not part of the default XWiki distribution!
209 {{/warning}}
210
211 The following is an example of mod_auth_kerb for Apache being used to easily implement Xwiki authentication of users via by HTTP Negotiate on a linux server. This example assumes you already have a working Apache2 HTTPD and Apache Tomcat setup with mod_jk.
212
213 First of all you need to create a principal and keytab for the webserver:
214
215 {{code}}
216 # kadmin
217 kadmin> addprinc -randkey HTTP/wiki.example.com
218 kadmin> ktadd -k /etc/apache2/ssl/wiki.keytab HTTP/wiki.example.com
219 kadmin> quit
220 {{/code}}
221
222 Make sure the keytab has the right permissions and ownership:
223
224 {{code}}
225 chown www-data:www-data /etc/apache2/ssl/wiki.keytab
226 chmod 400 /etc/apache2/ssl/wiki.keytab
227 {{/code}}
228
229 Install mod_auth_kerb in your linux installation. On Debian or Ubuntu this would be achieved by running:
230
231 {{code}}
232 aptitude install libapache2-mod-auth-kerb
233 {{/code}}
234
235 Of course the installation procedure varies per Linux distribution.
236
237 If your xwiki installation is mounted in Apache HTTPD under /xwiki, add the following to the virtual host configuration:
238
239 {{code}}
240 <Location /xwiki/>
241 AuthType Kerberos
242 AuthName "Kerberos Login"
243 KrbAuthRealms EXAMPLE.COM
244 Krb5Keytab "/etc/apache2/ssl/wiki.keytab"
245 KrbMethodK5Passwd off
246 KrbMethodNegotiate on
247 KrbSaveCredentials on
248 require valid-user
249 </Location>
250 {{/code}}
251
252 Make sure Apache Tomcat uses the authentication performed by Apache HTTPD with the "tomcatAuthentication" property in the connector description (which is in the server.xml file of Apache Tomcat):
253
254 {{code}}
255 <Connector port="8009" address="127.0.0.1" enableLookups="false" tomcatAuthentication="false" redirectPort="8443" protocol="AJP/1.3" />
256 {{/code}}
257
258 Place the authkerb.jar jar in the WEB-INF/lib directory of Xwiki in Apache Tomcat.
259
260 Have Xwiki use the authentication module by changing the "xwiki.authentication.authclass" property in WEB-INF/lib/xwiki.cfg file.
261
262 {{code}}
263 xwiki.authentication.authclass=com.xpn.xwiki.user.impl.xwiki.AppServerTrustedKerberosAuthServiceImpl
264 {{/code}}
265
266 If you use Firefox, do not forget to whitelist the xwiki URL for HTTP Negotiate in about:config with the "network.negotiate-auth.trusted-uris" property. possible values for this propperty include (without the quotes): "https:~/~/" for all secured connections or "example.com" for all example.com subdomains.
267
268 2 JBoss SPNEGO (Kerberos in combination with LDAP) I changed the code of the XWikiLDAPAuthServiceImpl to be able to detect the sso user. The authenication already happend by using the SPNEGO module (JAAS). After that I'm using the ldap synchronisation feature to make sure that the user is up to date. The combination leads to an automatic login in the xwiki and the user rights are controlled in the Active Directory server. I hope you can adopt this code or that you can use it for your own projects.
269
270 The configuration of ldap:
271
272 {{code}}
273 xwiki.authentication.authclass=com.wiki.sso.SSOLdapAuthenicationImpl
274 xwiki.authentication.ldap=1
275 xwiki.authentication.ldap.server=<ad-server>
276 xwiki.authentication.ldap.port=389
277 xwiki.authentication.ldap.base_DN=<OU=Users,...............>
278 #use a fixed user to attach to the ldap database,
279 #the password is not provided with the SSOLdapAuthenicationImpl
280 xwiki.authentication.ldap.bind_DN=<domain>\\<user>
281 xwiki.authentication.ldap.bind_pass=<password>
282 #Microsoft AD configuration
283 xwiki.authentication.ldap.UID_attr=sAMAccountName
284 xwiki.authentication.ldap.fields_mapping=name=sAMAccountName,last_name=sn,first_name=givenName,fullname=displayName,mail=mail,ldap_dn=dn
285 xwiki.authentication.ldap.group_memberfields=member,uniqueMember
286 #LDAP group mapping
287 xwiki.authentication.ldap.group_mapping=XWiki.XWikiAdminGroup=CN=WIKI_Admin,............|\
288 XWiki.XWikiAllGroup=CN=WIKI_User,...........
289 {{/code}}
290
291 The java code
292
293 {{code}}
294 package com.wiki.sso;
295
296
297 import org.apache.commons.logging.Log;
298 import org.apache.commons.logging.LogFactory;
299
300 import com.xpn.xwiki.XWikiContext;
301 import com.xpn.xwiki.XWikiException;
302 import com.xpn.xwiki.user.api.XWikiUser;
303 import com.xpn.xwiki.user.impl.LDAP.XWikiLDAPAuthServiceImpl;
304
305 import java.security.Principal;
306
307 public class SSOLdapAuthenicationImpl extends XWikiLDAPAuthServiceImpl {
308 /**
309 * Logging tool.
310 */
311 private static final Log LOG = LogFactory.getLog(SSOLdapAuthenicationImpl.class);
312
313
314 public XWikiUser checkAuth(XWikiContext context) throws XWikiException {
315 String user = getRemoteUser(context);
316 if ((user != null) || !user.equals("")) {
317 if (LOG.isInfoEnabled())
318 LOG.info("Launching create user for " + user);
319 if ( authenticate(user, context) != null ) {
320 if (LOG.isInfoEnabled())
321 LOG.info("Create user done for " + user);
322 user = "XWiki." + user;
323 context.setUser(user);
324 System.out.println("User is set to:" + user);
325 return new XWikiUser(user);
326 } else {
327 LOG.error( "User " + user + " can't be authenticated against ldap" );
328 }
329 }
330 return super.checkAuth(context);
331 }
332
333 /**
334 * We cannot authenticate locally since we need to trust the app server for
335 * authentication
336 *
337 * @param username
338 * @param password
339 * @param context
340 * @return
341 * @throws XWikiException
342 */
343 public XWikiUser checkAuth(String username, String password,
344 String rememberme, XWikiContext context) throws XWikiException {
345 String user = getRemoteUser(context);
346 if ((user == null) || user.equals("")) {
347 return super.checkAuth(username, password, rememberme, context);
348 }
349 return checkAuth(context);
350 }
351
352 private String getRemoteUser(XWikiContext context) {
353 String userName = context.getRequest().getHttpServletRequest()
354 .getRemoteUser();
355 if (userName != null) {
356 // only take the front of the username@domain
357 String[] elements = userName.split("@", 2);
358 userName = elements[0];
359 }
360 return userName;
361 }
362
363 public Principal authenticate(String login, XWikiContext context) throws XWikiException
364 {
365 if (LOG.isTraceEnabled()) {
366 LOG.trace("Starting LDAP authentication");
367 }
368
369 /*
370 * TODO: Put the next 4 following "if" in common with XWikiAuthService to ensure coherence This method was
371 * returning null on failure so I preserved that behaviour, while adding the exact error messages to the context
372 * given as argument. However, the right way to do this would probably be to throw XWikiException-s.
373 */
374
375 if (login == null) {
376 // If we can't find the username field then we are probably on the login screen
377
378 if (LOG.isDebugEnabled()) {
379 LOG.debug("The provided user is null."
380 + " We don't try to authenticate, it probably means the user is in non logged mode.");
381 }
382
383 return null;
384 }
385
386 // Check for empty usernames
387 if (login.equals("")) {
388 context.put("message", "nousername");
389
390 if (LOG.isDebugEnabled()) {
391 LOG.debug("LDAP authentication failed: login empty");
392 }
393
394 return null;
395 }
396
397 // If we have the context then we are using direct mode
398 // then we should specify the database
399 // This is needed for virtual mode to work
400 Principal principal = null;
401
402 // Try authentication against ldap
403 principal = ldapAuthenticate(login, "", context);
404
405 if (LOG.isDebugEnabled()) {
406 if (principal != null) {
407 LOG.debug("LDAP authentication succeed with principal [" + principal.getName() + "]");
408 } else {
409 LOG.debug("LDAP authentication failed for user [" + login + "]");
410 }
411 }
412
413 return principal;
414 }
415 }
416 {{/code}}

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected