JAAS Tomcat Login Module

Jump to: navigation, search


Released 14/1/2008


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 java.security.Principal, for users and roles.


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 java.security.Principal 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: public class UserPrincipal implements java.security.Principal and a role principal such as: public class RolePrincipal implements java.security.Principal When a user successfully authenticates, we add a UserPrincipal to the subject:

   principals.add(new UserPrincipal("bob"));

And then add any relevant roles:

   psr = con.prepareStatement(rolesQuery);
   psr.setInt(1, uid);
   rsr = psr.executeQuery();
   while (rsr.next()) {
        principals.add(new RolePrincipal(rsr.getString(1));

3 - Copy the necessary files to Tomcat's classpath

In the case of the OWASP TomcatTimedLoginModule, copy both the LoginModule itself: ./dist/OWASPJaasLoginModule.jar and the hsqldb.jar files (for DB access) to $CATALINA_HOME/server/lib

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:

   org.owasp.java.jaas.TomcatTimedLogin required 
       loginQuery="SELECT UserID,Password FROM Users WHERE UserName=?"
       rolesQuery="SELECT Roles.RoleName FROM Users_Roles,Roles WHERE Users_Roles.UserID=? AND Users_Roles.RoleID=Roles.RoleID";

Point Tomcat at the login file:

   export JAVA_OPTS=-Djava.security.auth.login.config==$CATALINA_HOME/conf/login.config

5 - Configure the security constraints in web.xml

Remember that the roles defined here are case-sensitive.

           <description>Only for administrators</description>

6 - Configure the JAASRealm in Tomcat's server.xml

For OWASP TomcatTimedLoginModule, the entry should be:

   <Realm className="org.apache.catalina.realm.JAASRealm"                 

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 org.apache.catalina.realm.JAASRealm

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 ant db-start to start the database, and ant db-populate to populate it with some test data.

Additional resources