Wiki source code of User Authentication

Version 36.1 by Thomas Mortagne on 2010/04/19

version	line-number	content
1.18	1	XWiki supports several different authentication mechanisms for authenticating users:
1.1	2
34.2	3	{{toc/}}
34.1	4
1.1	5	The form authentication is the default mechanism.
	6
34.1	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}}
1.1	10
34.2	11	= Form Authentication =
1.1	12
	13	TODO
	14
34.2	15	= LDAP Authentication =
1.1	16
34.1	17	{{warning}}
	18	New LDAP implementation since XWiki Platform 1.3M2, see [[previous LDAP authentication service documentation>>AuthenticationLdapOld]]
	19	{{/warning}}
17.3	20
34.2	21	== Generic LDAP configuration ==
1.1	22
34.1	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}}
7.1	26	## Turn LDAP authentication on - otherwise only XWiki authentication
	27	## 0 : disable
	28	## 1 : enable
1.2	29	xwiki.authentication.ldap=1
7.1	30
	31	## set LDAP as authentication service
18.1	32	xwiki.authentication.authclass=com.xpn.xwiki.user.impl.LDAP.XWikiLDAPAuthServiceImpl
34.1	33	{{/code}}
18.1	34
34.1	35	You can setup the LDAP configuration in the //xwiki.cfg// file by filling the following properties:
1.2	36
34.1	37	{{code language="none"}}
36.1	38	#-# LDAP Server (Active Directory, eDirectory, OpenLDAP, etc.)
	39	xwiki.authentication.ldap.server=127.0.0.1
1.1	40	xwiki.authentication.ldap.port=389
6.1	41
36.1	42	#-# LDAP login, empty = anonymous access, otherwise specify full dn
	43	#-# {0} is replaced with the username, {1} with the password
1.1	44	xwiki.authentication.ldap.bind_DN=cn={0},department=USER,department=INFORMATIK,department=1230,o=MP
	45	xwiki.authentication.ldap.bind_pass={1}
6.1	46
36.1	47	#-# Force to check password after LDAP connection
	48	#-# 0: disable
	49	#-# 1: enable
12.1	50	xwiki.authentication.ldap.validate_password=0
	51
36.1	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
6.1	55
36.1	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
22.1	58
36.1	59	#-# base DN for searches
6.1	60	xwiki.authentication.ldap.base_DN=
	61
36.1	62	#-# Specifies the LDAP attribute containing the identifier to be used as the XWiki name (default=cn)
	63	# xwiki.authentication.ldap.UID_attr=cn
6.1	64
36.1	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
6.1	67
36.1	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.
6.1	78	xwiki.authentication.ldap.update_user=1
	79
36.1	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
6.1	83
36.1	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
6.1	86
36.1	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
6.1	90
36.1	91	#-# if ldap authentication fails for any reason, try XWiki DB authentication with the same credentials
6.1	92	xwiki.authentication.ldap.trylocal=1
8.1	93
36.1	94	#-# SSL connection to LDAP server
	95	#-# 0: normal
	96	#-# 1: SSL
	97	# xwiki.authentication.ldap.ssl=0
8.1	98
36.1	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
34.1	104	{{/code}}
3.1	105
34.1	106	{{info}}
34.2	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##
34.1	108	{{/info}}
9.1	109
1.19	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
31.1	112	Here are some LDAP client for checking your configuration:
1.19	113
34.1	114	* [[Apache Directory Studio>>http://directory.apache.org/studio/]]
	115	* [[LDAP Browser/Editor>>http://www-unix.mcs.anl.gov/gawor/ldap/]]
1.19	116
34.2	117	== Detailed use cases ==
12.1	118
34.1	119	See [[LDAP configuration uses cases>>LDAPAuthenticationUseCases]] for some detailed use cases.
25.1	120
34.2	121	== Enable LDAP debug log ==
34.1	122
	123	See [[AdminGuide.Logging]]. The specific targets for LDAP authentication are:
	124
	125	{{code}}
25.1	126	log4j.logger.com.xpn.xwiki.plugin.ldap=debug
	127	log4j.logger.com.xpn.xwiki.user.impl.LDAP=debug
34.1	128	{{/code}}
27.1	129
34.2	130	= eXo Authentication =
30.1	131
34.1	132	The eXo authentication is used automatically by adding/editing the //xwiki.exo=1// property in //WEB-INF/xwiki.cfg//.
1.1	133
34.2	134	= Custom Authentication =
1.1	135
	136	This allows plugging to any existing authentication mechanism such as SiteMinder, etc. To configure a custom authentication do the following:
	137
34.1	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}}
1.1	142	xwiki.authentication.authclass = com.acme.MyCustomAuthenticationService
34.1	143	{{/code}}
1.1	144
34.1	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/]].
27.2	146
34.1	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}}
5.1	150	xwiki.authentication.rightsclass = com.acme.MyCustomRightsService
34.1	151	{{/code}}
4.1	152
34.1	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]]:
4.1	154
34.1	155	{{code}}
27.3	156	xwiki.authentication.groupclass = com.acme.MyCustomGroupService
34.1	157	{{/code}}
4.1	158
34.2	159	== Custom Authentication using a Groovy script in a wiki page ==
28.1	160
	161	Start by specifying you want to use the Groovy Authenticator:
	162
34.1	163	{{code}}
28.1	164	xwiki.authentication.authclass = com.xpn.xwiki.user.impl.xwiki.GroovyAuthServiceImpl
34.1	165	{{/code}}
28.1	166
	167	Then add another configuration parameter to specify in which wiki page the authenticator is:
	168
34.1	169	{{code}}
28.1	170	xwiki.authentication.groovy.pagename = MySpace.MyPage
34.1	171	{{/code}}
28.1	172
	173	Then in a wiki page put some Groovy code that returns a XWikiAuthService object.
	174
34.2	175	= Authentication parameters ===
1.14	176
	177	You can set each of these parameters by setting:
	178
34.1	179	{{code}}
1.14	180	xwiki.authentication.~~param_name~~=~~param_value~~
34.1	181	{{/code}}
1.14	182
34.1	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
35.1	195	\|loginsubmitpage\|Yes\|String\|/loginsubmit/ XWiki/XWikiLogin\|The URL where the username and password are posted to when logging in.
34.1	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
35.1	199	\|unauthorized_code\|Yes\|Number\|401\|The HTTP status code to return when the login has failed.
34.1	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.
1.16	201
34.1	202	1. Only required if protection = encryption or all (default)
	203	1. Only required if protection = validation or all (default)
1.17	204
34.2	205	= Kerberos SSO Authentication =
21.1	206
34.1	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
20.1	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.
1.18	212
20.1	213	First of all you need to create a principal and keytab for the webserver:
34.1	214
	215	{{code}}
20.1	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
34.1	220	{{/code}}
10.1	221
20.1	222	Make sure the keytab has the right permissions and ownership:
34.1	223
	224	{{code}}
20.1	225	chown www-data:www-data /etc/apache2/ssl/wiki.keytab
	226	chmod 400 /etc/apache2/ssl/wiki.keytab
34.1	227	{{/code}}
11.1	228
20.1	229	Install mod_auth_kerb in your linux installation. On Debian or Ubuntu this would be achieved by running:
34.1	230
	231	{{code}}
20.1	232	aptitude install libapache2-mod-auth-kerb
34.1	233	{{/code}}
	234
20.1	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:
34.1	238
	239	{{code}}
20.1	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>
34.1	250	{{/code}}
20.1	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):
34.1	253
	254	{{code}}
20.1	255	<Connector port="8009" address="127.0.0.1" enableLookups="false" tomcatAuthentication="false" redirectPort="8443" protocol="AJP/1.3" />
34.1	256	{{/code}}
20.1	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.
34.1	261
	262	{{code}}
20.1	263	xwiki.authentication.authclass=com.xpn.xwiki.user.impl.xwiki.AppServerTrustedKerberosAuthServiceImpl
34.1	264	{{/code}}
20.1	265
34.1	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.
20.1	267
34.1	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.
29.1	269
34.2	270	The configuration of ldap:
29.1	271
34.1	272	{{code}}
29.1	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,...........
34.1	289	{{/code}}
29.1	290
	291	The java code
34.1	292
	293	{{code}}
29.1	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	}
34.1	416	{{/code}}

Wiki source code of User Authentication

Quick Links

Navigation

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected