JAAS Tomcat Login Module

Status
Released 14/1/2008

Introduction
JAAS provides a powerful mechanism for integrating any authentication scheme into a Java application. But using JAAS for Java web applications is not as simple as just plugging in a standard JAAS module, because of the limited security functionality of the EE specification (users and roles), versus JAAS's more flexible approach to granting Principals. Luckily, Tomcat's requirements for a JAAS module are very easy to implement, all that's required is to use separate classes, derived from, for users and roles.

Process
Adapted from the Tomcat JAASRealm Quick Start guide.

1 - Create a custom JAAS LoginModule
There are many resources on the Internet explaining how this is done, including: the JAAS Developers guide. Or use an existing LoginModule such as the OWASP TomcatTimedLoginModule which is part of the OWASPTimedLoginModule package. More information about JAAS can be found at the JAAS tutorial

2 - Convert the LoginModule to work with Tomcat
The OWASP TomcatTimedLoginModule already works with Tomcat, but if you're developing one from scratch, then the following changes will have to be made. This involves assigning a class derived from  for the user Principal and another class for the roles that the user belongs to. Note that the first Principal returned must be the user Principal. For example, we could define a user principal class such as: and a role principal such as: When a user successfully authenticates, we add a UserPrincipal to the subject: And then add any relevant roles:

3 - Copy the necessary files to Tomcat's classpath
In the case of the OWASP TomcatTimedLoginModule, copy both the LoginModule itself:  and the   files (for DB access) to

4 - Create a JAAS login configuration file
The configuration file should contain startup parameters needed by the module. For the TomcatTimedLoginModule, the configuration file is: Point Tomcat at the login file:

5 - Configure the security constraints in web.xml
Remember that the roles defined here are case-sensitive.

6 - Configure the JAASRealm in Tomcat's server.xml
For OWASP TomcatTimedLoginModule, the entry should be: The userClassNames and roleClassNames values correspond to the classes used to store the user and role Principals respectively. The appName value corresponds to the name given to the entry in the login.config file defined in step 4. The className is always

7 - Start dependant resources and restart Tomcat
To test the TomcatTimedLoginModule, a simple HSQLDB database is provided. Edit the build.xml and change the location of the hsqldb.jar file, and run  to start the database, and   to populate it with some test data.

Additional resources

 * Declarative J2EE authentication and authorization with JAAS