[The content of this page is outdated, it is maintained for archival purpose only]

Integrating Shibboleth and Tomcat

This page describes some of the issues integrating Shibboleth and Tomcat.


1. Versions

We're using tomcat 5.5.16, mod_jk connector 1.2.15 and the reference implementation of Shibboleth version 1.3c. We're running on a Linux (RedHat Enterprise / Scientific Linux) environment.

Our goal is to provide Shibboleth authenticatiion information to a Sakai portal server running under Tomcat, but the initial experiments described here have been conducted using one of the Tomcat example servlets /jsp-examples/snp/snoop.jsp, since this also echoes the remote username for the serviced request.

2. General setup

To perform Shibboleth authentication, we are using Apache httpd to front the Tomcat servlet environment. The Shibboleth service provider (the so-called C SP module) installs as an Apache module (mod_shib) and a supporting daemon process (shibd). The Apache server communicates with Tomcat using AJP/1.3 protocol via the JK connector.

Configuration details can be found at http://wiki.oss-watch.ac.uk/TomcatNotes#JKConnector.

Note in particular that the connector configuration in Tomcat's server.xml file must specify tomcatAuthentication="false" in order to recognize Apache https authentication (including the authenticated username, which is provided using a REMOTE_USER header):

<Connector port="8009"


We configure Shibboleth to set the value of REMOTE_USER to the value of urn:mace:dir:attribute-def:oucsPrimaryUsername, which itself was derived from the oucsPrimaryUsername in the underlying OUCS LDAP entry.

3. Apache httpd authentication and Tomcat

The above configuration is sufficient for Tomcat servlets to be able to retrieve the authenticated username using request.getRemoteUser(), but does not of itself establish servlet invocation as being authenticated. For this, it is necessary to place a <security-constraint> on the context URI that is used to invoke the servlet. This is done in the web applications web.xml file.

For example, to authenticate use of the "snoop.jsp" example page that is part of the standard Tomcat "jsp-examples" application, edit $CATALINA_HOME/webapps/jsp-examples/WEB-INF/web.xml to contain the following:

</security-constraint> }}}

This requires that any acess to /jsp-examples/snp/* be authenticated to any of the roles declared to Tomcat elsewhere in the web.xml file. The problem with this when receiving authentication information from Apache httpd via mod_jk is that we have not found any way to associate role membership with the authenticated user. As a result, Tomcat refuses access to the servlet, even though we do appear to have successfully conveyed authenticated user information to Tomcat.

It appears that when Tomcat's own authentication is bypassed (using tomcatAuthentication="false" noted above), Tomcat's mechanisms for assigning roles to users (e.g. from tomcat-users.xml) are also bypassed, so the authentication is effectively useless for invoking servlets.

Thus, we need to find another way of getting Tomcat to recognize Shibboleth authentication information, and thus provide authenticatuion services (JAAS) to the running servlet.

4. SPIE JAAS module

The SPIE JAAS module https://spie.oucs.ox.ac.uk/Wiki.jsp?page=JAASmodule2 can be used to provide attributes from a Shibboleth SAML assertion conveyed in an HTTP request header via normal servlet authentication interfaces (i.e. as principals in a JAAS framework structure).

spiejaasprincipals.1.13.jar spiejaaswebappsupport.1.16.jar spietestservlet.1.21.war }}}



}; }}}

}; }}}


</Location> }}}

Stuart: This much seems to work now with the spietestservlet. (This servlet is v. useful -- check out the headers display!) I've applied an edit to resolver.ldap.xml so that oucsPrimaryName is released as eduPersonPrincipalName (noted on the relevant wiki page). Next steps are to (a) repeat tests with the jsp-example snoop page - this gives us a kind of independent test Done - see below. Then return to testing the Sakai login.

Testing with spietestservlet to date shows we are getting the username into the JAAS module. The notes below indicate how roles might (should?) be handled. This may need a touch of fancy LDAP mapping?

The following was added to SakaiVre/SakaiUserDirectoryProvider, but I think some of it also belongs here, so I've duplicated it for now.

In order to get Shib-EP-Principalname passed to Tomcat, uncomment the following in AAP.xml (and edit the "Header=" attribute if necessary):

</AttributeRule> }}}

The refers to application context parameters or servlet init parameters that may be defined in the application's web.xml configuration file. This example comes from the SPIE test servlet configuration:

Here, parameter 'attributeAsUsername' indicates Shibboleth attributes that are mapped to JAAS principals, and 'attributeAsRoles' indicates an attribute that conveys roles that have been assigned to the authenticated user.

4.1. Testing with https://wayf.internet2.edu/InQueue/sample.jsp

The login procedure proceeds as expected, and the test page displays the following information. Of particular note is that we're now seeing Shib-EP-PrincipalName, which is the Shibboleth attribute name used (by the SPIE project, at least) for conveying the user id information to an application/portal.

The attribute in the SAML assertion corresponding to Shib-EP-PrincipalName is this:

</Attribute> }}}

(I've obscured my actual Oxford login name above as XXXXXX, but the values actually given were correct.)

This actually tests less than the JAAS test module, since it only echos what is provided by the InQueue sample.jsp in conjunction with its AAP.

I'm currently a little puzzled by this result - does it mean that the inQueue AAP happens to contain the same AttributeRule as we have just created?

5. References

-- StuartYeates 2006-07-12 14:06:24

Creative Commons License
The content of this wiki is licensed under the Creative Commons Attribution-ShareAlike 2.0 England & Wales Licence.

OSS Watch is funded by the Joint Information Systems Committee (JISC) and is situated within the Research Technologies Service (RTS) of the University of Oxford.