How to: Integrate Waffle in XWiki using Tomcat on Windows
-
Make sure to install the LDAP Authenticator extension (https://extensions.xwiki.org/xwiki/bin/view/Extension/LDAP/Authenticator/).
-
Run the Tomcat service using a domain service account. You will need to set the service principal name (SPN) for the service account as noted in the Waffle documentation (https://github.com/Waffle/waffle/blob/master/Docs/faq/NegotiateFailsWith401.md). Make sure that the domain service account has permission to write to the
temp
,logs
,work
, etc. in the Tomcat installation directory. -
Download Waffle - https://github.com/Waffle/waffle (version 1.9.0 is the latest as I write this)
-
Copy the following files from the Waffle distribution into the Tomcat
lib
directory:caffeine-2.6.2.jar jcl-over-slf4j-1.7.25.jar jna-4.5.1.jar jna-platform-4.5.1.jar slf4j-api-1.7.25.jar slf4j-simple-1.7.25.jar waffle-jna-1.9.0.jar waffle-tomcat9-1.9.0.jar
(If you’re not using Tomcat 9, copy the correct waffle-tomcat*-1.9.0.jar file for your Tomcat version.)
-
For XWiki 10.8, add
Valve
andRealm
tags inMETA-INF\context.xml
:<?xml version="1.0" encoding="UTF-8"?> <Context containerSciFilter="org.apache.tomcat.websocket.server.WsSci|org.apache.jasper.servlet.JasperInitializer"> <Valve className="waffle.apache.NegotiateAuthenticator" principalFormat="fqn" roleFormat="both" protocols="Negotiate,NTLM" /> <Realm className="waffle.apache.WindowsRealm" /> <JarScanner> <JarScanFilter defaultTldScan="false"/> </JarScanner> </Context>
For XWiki versions older than 10.8, you’ll need to create a new
context.xml
file containing only theValve
andRealm
tags:<?xml version="1.0" encoding="UTF-8"?> <Context> <Valve className="waffle.apache.NegotiateAuthenticator" principalFormat="fqn" roleFormat="both" protocols="Negotiate,NTLM" /> <Realm className="waffle.apache.WindowsRealm" /> </Context>
-
Modify
WEB-INF\web.xml
to add the<security-constraint>
and<security-role>
restrictions you want. Place these settings before the first<filter>
tag in the file; e.g.:<security-constraint> <web-resource-collection> <web-resource-name>XWiki</web-resource-name> <url-pattern>/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>FABRIKAM\XWiki Users</role-name> </auth-constraint> </security-constraint> <security-role> <role-name>FABRIKAM\XWiki Users</role-name> </security-role>
This example prevents authentication to the web server unless the connecting user is a member of the
XWiki Users
group in theFABRIKAM
domain. -
Modify
WEB-INF\xwiki.cfg
to use the LDAP Authenticator settings you want to use; e.g.:xwiki.authentication.authclass=org.xwiki.contrib.ldap.XWikiLDAPAuthServiceImpl xwiki.authentication.ldap=1 xwiki.authentication.ldap.remoteUserParser=(.+)\\\\(.+) xwiki.authentication.ldap.remoteUserMapping.2=uid xwiki.authentication.ldap.server=fabdc1.fabrikam.com xwiki.authentication.ldap.port=389 xwiki.authentication.ldap.base_DN=DC=fabrikam,DC=com xwiki.authentication.ldap.bind_DN=FABRIKAM\\LDAPAuth xwiki.authentication.ldap.bind_pass=LDAPAuthAccountPassword xwiki.authentication.ldap.UID_attr=sAMAccountName xwiki.authentication.ldap.fields_mapping=name=sAMAccountName,last_name=sn,first_name=givenName,fullname=displayName,email=mail,ldap_dn=dn
This example searches the
fabrikam.com
domain using the specified LDAP auth username and password. Unfortunately, we have to hard-code the LDAP auth account password inxwiki.cfg
because the LDAP Authenticator extension requires it. I would recommend restricting access to theWEB-INF
directory permissions because of this. (In the future if the LDAP Authenticator extension is updated to be able to perform an LDAP server binding using current credentials,the xwiki.authentication.ldap.bind_DN
andxwiki.authentication.ldap.bind_pass
settings will not be needed.)
I have successfully set up restricted access using Windows domain authentication using this configuration. I can update this post in case I’ve forgotten any details.