What is a Tomcat Valve?
This guide does not explain or cover Tomcat Valves nor does it describe best practice/course of action when implementing Tomcat Valves.
The purpose of this guide is to simply illustrate that the SPNEGO HTTP Servlet Filter library's API can easily be used/leveraged by custom third-party code/frameworks.
This guide does provide source code as well as step-by-step instructions on how to configure Tomcat to silently authenticate users via a Tomcat Valve that uses Kerberos/SPNEGO as the authentication mechanism.
Finally, it appears that the latest version of Tomcat (7) will use servlet filters to replace/deprecate valves:
By default, Tomcat supports such authentication mechanisms as
But fortunately, Tomcat does allow you to implement and specify your own authentication mechanism via
Tomcat Valves and the
Tomcat also provides a framework for mapping users to roles. By default, this mapping definition is
specified in Tomcat's
Goals of this guide:
Before Getting Started
If you don't already have a working tomcat server that authenticates requests via Kerberos/SPNEGO, take a look at the installing Tomcat example. After install, ensure that authentication is working by running the hello_spnego.jsp example. It is imperative that you get this working first since we will be using the values you provided in the web.xml file, and the creation of the krb5.conf file and the login.conf file.
This guide requires that you are able to get the HTTP Servlet Filter working first.
Once you have confirmed that all is working as expected (via the HTTP Servlet Filter method), be sure to remove/comment-out the HTTP Servlet Filter definition and filter mapping from the web.xml file.
Obviously authentication will now fail but now we are ready to get it working again via Tomcat Valves.
Download the latest spnego.jar
file (spnego-r7.jar or greater) and place it under the
Download the ExampleSpnegoAuthenticatorValve.java
code and place it under the
Before compiling ExampleSpnegoAuthenticatorValve.java, be sure to change the hard-coded property values in the file. These values should be the same values which was used in your old web.xml file (your old web.xml file had the filter definition and mapping defined and your new web.xml does not or is commented-out).
You will also need to add
After compilation, you need to
Modifying the Authenticators.properties file
The Authenticators.properties file is located inside
Open the file in a text editor and append the following to the list of authenticators:
Modifying the tomcat-users.xml file
By default, Tomcat stores the username/role(s) mapping in the
This guide will use the
<?xml version='1.0' encoding='utf-8'?> <tomcat-users> <role rolename="manager"/> <role rolename="role1"/> <role rolename="role2"/> <user username="DFelix@ATHENA.LOCAL" password="" roles="manager,role1"/> </tomcat-users>
Notice that the value for the username attribute is fully qualified. If you want leave out the
Also notice that the value for the password attribute is an empty string. This value coincides with the call
Modifying the web.xml file
Add the following to the web.xml file:
<security-constraint> <web-resource-collection> <web-resource-name>All JSP Files</web-resource-name> <url-pattern>*.jsp</url-pattern> </web-resource-collection> <auth-constraint> <role-name>role1</role-name> </auth-constraint> </security-constraint> <login-config> <auth-method>SPNEGO</auth-method> </login-config> <security-role> <role-name>role1</role-name> </security-role>
Notice that we no longer need to define the SPNEGO HTTP Servlet Filter in the web.xml file.
Open a browser and go to http://medusa:8080/hello_spnego.jsp
If all is working correctly you should see the following (without being prompted):
If you have not yet noticed, take a look again at the web.xml file. Notice that the
Also remember that the source for the user/role mapping (AuthZ) does not have to be defined in a .xml file; you can specify JDBC, LDAP, etc. as the store for the user/role mapping.
Essentially, Tomcat allows for an AuthN/AuthZ mechanism that is both loosely-coupled and highly-cohesive.
The first step to troubleshooting the Tomcat Valve is to first know with absolute certainty that authentication was working when it was configured as an HTTP Servlet Filter.
Visit the Tomcat Valve troubleshooting page to see a list of possible solutions to some common errors.
© 2009 Darwin V. Felix. All rights reserved.