Tomcat, Atlassian Crowd and JAAS

Written By: Grigori Goldman

September 19, 2010

I have recently rolled out a single sign-on solution using Atlassian Crowd. My client’s applications were running on Apache Tomcat and required FORM based authentication. After briefly Googling around, I have found the Crowd JAAS Login Module (see which fitted my requirements perflectly.

Here is an example of how to integrate a Crowd JAAS login module into Tomcat so that all web applications can be authenticated against the Crowd server.

The following instructions were tested against Crowd 2.0 and Tomcat 6.0.29. You will need at least Tomcat 6.0.20 to make some of the instructions that follow work.

First step is to prepare the Tomcat server to authenticate users against Crowd. To ensure that you can still log into the Tomcat manager application, wrap the UserDatabase realm in a CombinedRealm element (note the CombinedRealm class is only available in Tomcat 6.0.20 and above). Add the Crowd realm definition inside the CombinedRealm as well.

Note: You don’t have to do this if you intend to add your Tomcat administrator user and roles to Crowd. If you do, then you can repalce the UserDatabase realm with your Crowd realm.

If you need single sign-on, make sure to uncomment the SingleSignOn valve inside the Host element.


I don’t like to mix Tomcat core libraries with third party libraries. So, instead of adding the Crowd login module library (and its dependencies) to the Tomcat’s lib directory, create a new directory, lib-crowd and add a reference to it in the file. For example:


Which dependencies do you need? Truthfully, I haven’t properly worked that out yet. Besides the CrowdJaasLoginModule-{version}.jar and crowd-integration-client-{version}.jar, I basically added all the jars that I found in the Crowd client/lib directory.

Finally, we need to configure the Crowd JAAS module. Add a crowd.conf file to Tomcat’s conf directory. Here is a basic JAAS module configuration to get you started (see the Crowd JAAS Login Module wiki for a full list of all the options that you can use).


Edit: As was pointed out in the comment below, the Tomcat JVM must be told which JAAS login configuration file should be used. The best way is to add the following entry to the CATALINA_OPTS environment variable that is usually initialised in the startup.[sh|bat] or setenv.[sh|bat] scripts:$CATALINA_HOME/conf/crowd.conf

And that’s it. Well, not quite. I did have some issues with getting Tomcat to recognise the user roles that were added to the Subject by the JAAS module. I posted a solution to this problem to this forum: .