Wiki source code of User Authentication

Version 42.1 by Thomas Mortagne on 2011/06/22
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 Form authentication is the default way to get authenticated within a Wiki. It requires a user and a password.
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##. The contributed extension [[LDAP Tools>>extensions:Extension.LDAP Tools]] provides a administration section UI to configure LDAP from the wiki in a simpler manner.
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 * [[LDAPExplorerTool>>http://ldaptool.sourceforge.net/]]
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]].
124
125 The specific packages to track for LDAP are ##com.xpn.xwiki.plugin.ldap## and ###com.xpn.xwiki.user.impl.LDAP#.##
126
127 Before 3.1, add the following to the log4j configuration file:
128 {{code}}log4j.logger.com.xpn.xwiki.plugin.ldap=trace
129 log4j.logger.com.xpn.xwiki.user.impl.LDAP=trace{{/code}}
130
131 = eXo Authentication =
132
133 The eXo authentication is used automatically by adding/editing the //xwiki.exo=1// property in //WEB-INF/xwiki.cfg//.
134
135 = Custom Authentication =
136
137 This allows plugging to any existing authentication mechanism such as SiteMinder, etc. To configure a custom authentication do the following:
138
139 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.
140 1. Edit the //WEB-INF/xwiki.cfg// file and add a //xwiki.authentication.authclass// property pointing to your class. For example:
141
142 {{code}}
143 xwiki.authentication.authclass = com.acme.MyCustomAuthenticationService
144 {{/code}}
145
146 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/]].
147
148 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:
149
150 {{code}}
151 xwiki.authentication.rightsclass = com.acme.MyCustomRightsService
152 {{/code}}
153
154 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]]:
155
156 {{code}}
157 xwiki.authentication.groupclass = com.acme.MyCustomGroupService
158 {{/code}}
159
160 == Custom Authentication using a Groovy script in a wiki page ==
161
162 Start by specifying you want to use the Groovy Authenticator:
163
164 {{code}}
165 xwiki.authentication.authclass = com.xpn.xwiki.user.impl.xwiki.GroovyAuthServiceImpl
166 {{/code}}
167
168 Then add another configuration parameter to specify in which wiki page the authenticator is:
169
170 {{code}}
171 xwiki.authentication.groovy.pagename = MySpace.MyPage
172 {{/code}}
173
174 Then in a wiki page put some Groovy code that returns a XWikiAuthService object.
175
176 = Authentication parameters =
177
178 You can set each of these parameters by setting:
179
180 {{code}}
181 xwiki.authentication.~~param_name~~=~~param_value~~
182 {{/code}}
183
184 |=Name|=Optional|=Allowed values|=Default value|=Description
185 |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.
186 |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.
187 |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
188 |cookielife|Yes|Number|14|Number of days cookies take to expire
189 |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//
190 |default_page|Yes|String|/bin/view/ Main/WebHome|Page to redirect to if xredirect parameter is not set
191 |encryptionalgorithm|Yes|?|?|Set the Encryption Algorithm used to encrypt and decrypt cookies
192 |encryptionmode|Yes|?|?|Set the Encryption Mode used to encrypt and decrypt cookies
193 |encryptionpadding|Yes|?|?|Set the Encryption Padding used to encrypt and decrypt cookies
194 |errorpage|Yes|String|/bin/loginerror/ XWiki/XWikiLogin|Page to redirect to if there is an error logging in
195 |loginpage|Yes|String|/bin/login/ XWiki/XWikiLogin|Page to redirect to when not logged in
196 |loginsubmitpage|Yes|String|/loginsubmit/ XWiki/XWikiLogin|The URL where the username and password are posted to when logging in.
197 |logoutpage|Yes|String|/bin/logout/ XWiki/XWikiLogout|Page to redirect to after logged out
198 |realmname|Yes|String|XWiki|Sets the realm name
199 |protection|Yes|all, validation, encryption, none|all|Protection level for the "remember me" cookie functionality
200 |unauthorized_code|Yes|Number|401|The HTTP status code to return when the login has failed.
201 |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.
202
203 1. Only required if protection = encryption or all (default)
204 1. Only required if protection = validation or all (default)
205
206 = Kerberos SSO Authentication =
207
208 {{warning}}
209 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!
210 {{/warning}}
211
212 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.
213
214 First of all you need to create a principal and keytab for the webserver:
215
216 {{code}}
217 # kadmin
218 kadmin> addprinc -randkey HTTP/wiki.example.com
219 kadmin> ktadd -k /etc/apache2/ssl/wiki.keytab HTTP/wiki.example.com
220 kadmin> quit
221 {{/code}}
222
223 Make sure the keytab has the right permissions and ownership:
224
225 {{code}}
226 chown www-data:www-data /etc/apache2/ssl/wiki.keytab
227 chmod 400 /etc/apache2/ssl/wiki.keytab
228 {{/code}}
229
230 Install mod_auth_kerb in your linux installation. On Debian or Ubuntu this would be achieved by running:
231
232 {{code}}
233 aptitude install libapache2-mod-auth-kerb
234 {{/code}}
235
236 Of course the installation procedure varies per Linux distribution.
237
238 If your xwiki installation is mounted in Apache HTTPD under /xwiki, add the following to the virtual host configuration:
239
240 {{code}}
241 <Location /xwiki/>
242 AuthType Kerberos
243 AuthName "Kerberos Login"
244 KrbAuthRealms EXAMPLE.COM
245 Krb5Keytab "/etc/apache2/ssl/wiki.keytab"
246 KrbMethodK5Passwd off
247 KrbMethodNegotiate on
248 KrbSaveCredentials on
249 require valid-user
250 </Location>
251 {{/code}}
252
253 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):
254
255 {{code}}
256 <Connector port="8009" address="127.0.0.1" enableLookups="false" tomcatAuthentication="false" redirectPort="8443" protocol="AJP/1.3" />
257 {{/code}}
258
259 Place the authkerb.jar jar in the WEB-INF/lib directory of Xwiki in Apache Tomcat.
260
261 Have Xwiki use the authentication module by changing the "xwiki.authentication.authclass" property in WEB-INF/lib/xwiki.cfg file.
262
263 {{code}}
264 xwiki.authentication.authclass=com.xpn.xwiki.user.impl.xwiki.AppServerTrustedKerberosAuthServiceImpl
265 {{/code}}
266
267 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.
268
269 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.
270
271 The configuration of ldap:
272
273 {{code}}
274 xwiki.authentication.authclass=com.wiki.sso.SSOLdapAuthenicationImpl
275 xwiki.authentication.ldap=1
276 xwiki.authentication.ldap.server=<ad-server>
277 xwiki.authentication.ldap.port=389
278 xwiki.authentication.ldap.base_DN=<OU=Users,...............>
279 #use a fixed user to attach to the ldap database,
280 #the password is not provided with the SSOLdapAuthenicationImpl
281 xwiki.authentication.ldap.bind_DN=<domain>\\<user>
282 xwiki.authentication.ldap.bind_pass=<password>
283 #Microsoft AD configuration
284 xwiki.authentication.ldap.UID_attr=sAMAccountName
285 xwiki.authentication.ldap.fields_mapping=name=sAMAccountName,last_name=sn,first_name=givenName,fullname=displayName,mail=mail,ldap_dn=dn
286 xwiki.authentication.ldap.group_memberfields=member,uniqueMember
287 #LDAP group mapping
288 xwiki.authentication.ldap.group_mapping=XWiki.XWikiAdminGroup=CN=WIKI_Admin,............|\
289 XWiki.XWikiAllGroup=CN=WIKI_User,...........
290 {{/code}}
291
292 The java code
293
294 {{code}}
295 package com.wiki.sso;
296
297
298 import org.apache.commons.logging.Log;
299 import org.apache.commons.logging.LogFactory;
300
301 import com.xpn.xwiki.XWikiContext;
302 import com.xpn.xwiki.XWikiException;
303 import com.xpn.xwiki.user.api.XWikiUser;
304 import com.xpn.xwiki.user.impl.LDAP.XWikiLDAPAuthServiceImpl;
305
306 import java.security.Principal;
307
308 public class SSOLdapAuthenicationImpl extends XWikiLDAPAuthServiceImpl {
309 /**
310 * Logging tool.
311 */
312 private static final Log LOG = LogFactory.getLog(SSOLdapAuthenicationImpl.class);
313
314
315 public XWikiUser checkAuth(XWikiContext context) throws XWikiException {
316 String user = getRemoteUser(context);
317 if ((user != null) || !user.equals("")) {
318 if (LOG.isInfoEnabled())
319 LOG.info("Launching create user for " + user);
320 if ( authenticate(user, context) != null ) {
321 if (LOG.isInfoEnabled())
322 LOG.info("Create user done for " + user);
323 user = "XWiki." + user;
324 context.setUser(user);
325 System.out.println("User is set to:" + user);
326 return new XWikiUser(user);
327 } else {
328 LOG.error( "User " + user + " can't be authenticated against ldap" );
329 }
330 }
331 return super.checkAuth(context);
332 }
333
334 /**
335 * We cannot authenticate locally since we need to trust the app server for
336 * authentication
337 *
338 * @param username
339 * @param password
340 * @param context
341 * @return
342 * @throws XWikiException
343 */
344 public XWikiUser checkAuth(String username, String password,
345 String rememberme, XWikiContext context) throws XWikiException {
346 String user = getRemoteUser(context);
347 if ((user == null) || user.equals("")) {
348 return super.checkAuth(username, password, rememberme, context);
349 }
350 return checkAuth(context);
351 }
352
353 private String getRemoteUser(XWikiContext context) {
354 String userName = context.getRequest().getHttpServletRequest()
355 .getRemoteUser();
356 if (userName != null) {
357 // only take the front of the username@domain
358 String[] elements = userName.split("@", 2);
359 userName = elements[0];
360 }
361 return userName;
362 }
363
364 public Principal authenticate(String login, XWikiContext context) throws XWikiException
365 {
366 if (LOG.isTraceEnabled()) {
367 LOG.trace("Starting LDAP authentication");
368 }
369
370 /*
371 * TODO: Put the next 4 following "if" in common with XWikiAuthService to ensure coherence This method was
372 * returning null on failure so I preserved that behaviour, while adding the exact error messages to the context
373 * given as argument. However, the right way to do this would probably be to throw XWikiException-s.
374 */
375
376 if (login == null) {
377 // If we can't find the username field then we are probably on the login screen
378
379 if (LOG.isDebugEnabled()) {
380 LOG.debug("The provided user is null."
381 + " We don't try to authenticate, it probably means the user is in non logged mode.");
382 }
383
384 return null;
385 }
386
387 // Check for empty usernames
388 if (login.equals("")) {
389 context.put("message", "nousername");
390
391 if (LOG.isDebugEnabled()) {
392 LOG.debug("LDAP authentication failed: login empty");
393 }
394
395 return null;
396 }
397
398 // If we have the context then we are using direct mode
399 // then we should specify the database
400 // This is needed for virtual mode to work
401 Principal principal = null;
402
403 // Try authentication against ldap
404 principal = ldapAuthenticate(login, "", context);
405
406 if (LOG.isDebugEnabled()) {
407 if (principal != null) {
408 LOG.debug("LDAP authentication succeed with principal [" + principal.getName() + "]");
409 } else {
410 LOG.debug("LDAP authentication failed for user [" + login + "]");
411 }
412 }
413
414 return principal;
415 }
416 }
417 {{/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