Struts, JAAS, Tomcat: getting acquainted html

Struts, JAAS, Tomcat: getting acquainted

The Java Authentication + Authorization Service (JAAS) provides a standard API for making non-standard (i.e. custom) realms available to your application server, see e.g. this article on JavaWorld. To reiterate, a realm is a “database” of usernames, passwords and roles that identify valid users of a (web) application, where multiple roles may be associated to one user. JAAS’s pluggable nature makes it an ideal candidate to integrate legacy realms into your J2EE architecture.

In this post it will be shown how to set up a JAAS-based authentication mechanism for a realm that is disclosed via Hibernate, which in turn talks to SQL server database provided with a JDBC driver. In a subsequent post I’ll discuss authorisation issues.

We applied JAAS + Struts under Tomcat to the application that has been described in Hibernate + Middlegen Roundtrip Development applied, which basically is J2EE-based web application based on a legacy SQL server database, that uses Hibernate as ORM framework and Struts as MVC solution.

First we will present some background info and refs on JAAS, Struts & JAAS and Tomcat separately, thereafter it will be presented how this knowledge was applied to our case.

Introductory material on JAAS

If you are completely new to JAAS, the first four paragraphs of “All That JAAS, Pluggable authentication and authorization services provide many key security benefits for Java applications” by Kevin Jones give a nice description. In addition, you may find the following links useful:

JAAS and Struts

Using JAAS for Authorization and Authentication by Dan Moore starts with a few definitions which are very important to understand when dealing with J2EE security, such as Subject, Principal and Realm.

Thereafter it is shown how to set up JAAS for a Struts based application. More specifically, Dan Moore discusses an example (source can be downloaded) where he uses an implementation of a JAAS LoginModule, that performs authentication against a plain file, that contains usernames, (MD5 encrypted) passwords and roles. This LPGL licensed implementation is offered by the project, providing implementations for LoginModules against JDBC connected databases, Windows NT Domains and text files, as we just mentioned above.

Authorisation is done by extending the Struts ActionServlet, which would preferrably have been done by using filters, but this is postponed for my post on authorisation.

Dan Moore’s article puts the whole framework basically in place, although we want (actually we need to) modify the location of the JAR file containing the implementation for the LoginModule: since we are going to use Hibernate to extract the authentication information from the database, it is necessary for the LoginModule to “live” inside the web application context.

Tomcat’s container managed security

This section basically boils down to a JAAS-focussed summary of Tomcat Realm HOWTO.

The servlet specification defines how to declare security requirements in the web.xml deployment descriptor, but there is no strandard API for sevlet container < -> web application user/role-related information exchange, hence all solutions are application server specific.

Tomcat 5’s solution: the org.apache.catalina.Realm interface. Currently, 5 different realms are supported:

  1. MemoryRealm, this is the default and perhaps most well-known realm, namely the tomcat-users.xml file.
  2. JDBCRealm, for relational databases accessed via a JDBC driver.
  3. JNDIRealm, for LDAP based realms accessed via JNDI.
  4. JAASRealm, need I say more πŸ˜‰
  5. DataSourceRealm, for relational databases accessed via a JNDI DataSource.

Realm configuration is done in the conf/server.xml by adding an XML element. Important: the scope of the realm is defined here!

  • All web applications on all virtual hosts
  • All web applications for this virtual host
  • Only this web application on this virtual host

This is discussed in detail in this part of the HOWTO, but this thread on Sun’s Developer Forums is much more detailed! Escpecially step 1 from the HOWTO is worth a complete page: see the LoginModule Developers Guide.

Note: If you are just an application programmer who wants to use an existing JAAS LoginModule (implementation), you don’t need to delve any deeper into this issue, of course! In our case it was needed, since we had to do authentication based on data residing in a (custom) legacy SQL server database.

Putting all the pieces together

Following the recipe from this thread:

  1. Following the LoginModule Developers Guide, we implemented our own HibernateLoginModule. Basically, we took the source code of the file-based LoginModule, replacing the code where the JDBC realm was involved with Hibernate-based code. Moreover, an AmisHoursPrincipal and AmisHoursPrincipalRole were implemented. This implementation reflects the authentication information of our legacy system, but was not complicated.

    Each user corresponds to a Resource table in the database, and has a many-to-one relationship with the ResourceGroup, which in turn corresponds to a Principal.

    As shown in the example on discussed on the Sun’s developers Forum, AmisHoursPrincipalRole merely extends from AmisHoursPrincipal.

  2. An AuthenticationBusinessComponent was written to carry out the actual task of authentication. This component is completely analogous to Dan Moore’s example (where the LoginContext is used), including the callback handler, which takes care of passing the username/password information provided via the web interface back to the JAAS LoginModule, albeit some small changes, e.g. in our legacy database passwords are stored unencrypted.

    By the way, have things completely under our control now, we may now easily upgrade our legacy application to use MD5 encrypted passwords!

  3. The Struts LogonAction was modified to include a call to the aforementioned authentication business component.
  4. The associated entry was placed in the conf/server.xml

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

  5. The $JAVA_HOME/jre/lib/security/ file was changed to include the following JAAS entry:

    Of course, there are more options available to make the location of this file known to the JVM/Tomcat.

  6. The file, referred to from the above mentioned, contains the following info:

    nl.amis.hours.auth.HibernateLoginModule required debug=true;

    Note that the name DatabaseLogin is used in the authentication business component (!):

    public boolean authenticate()
            loginContext = new LoginContext("DatabaseLogin",
                new MyCallBackHandler(username, password));
        catch (LoginException le)
            log.error("LoginException: " + le);
            return false;
        return true;
  7. Since our LoginModule “lives” in the application context i.e., the JAAS sources are on equal footing with the remainder of the sources of this (Eclipse) project, all above mentioned Java class files are part of the final WAR file. Therefore Tomcat can find these classes and is happy, and so are we πŸ™‚

    Now all that is left is to restart Tomcat, if you didn’t do so already!


  1. orbit September 18, 2009
  2. mark January 20, 2006
  3. Fred Thurber September 29, 2005
  4. Rami Zanoun August 19, 2005
  5. source code August 17, 2005
  6. buetikofer August 4, 2005
  7. Zeger Hendrikse March 30, 2005
  8. Joao March 30, 2005
  9. Partha Pal February 3, 2005
  10. Zeger Hendrikse November 19, 2004
  11. Jasper November 17, 2004