Preparing Apache Tomcat for the Shibboleth Identity Provider

Version Requirements/Recommendations

Apache Tomcat 6.0.17 or greater (officially supported)
Apache Tomcat 7 or later (SOAP works with 3rd party tomcat-dta-ssl but this plugin is not officially supported by the Shibboleth project)
Java 6 or later (see additional notes in IdPInstall)

Tomcat 7 is officially supported only if you don't require support for SOAP traffic on the additional port, or are prepared to deploy an Apache web server as the "front-end" to the Tomcat service. This is a consequence of there not being a supported specialized certificate evaluation override for Tomcat that delegates evaluation of SP certificates to the IdP application. It is impractical in most deployments to rely on Tomcat to perform its standard methods of client certificate validation.

However, Unicon has ported this certificate evaluation override component to Tomcat 7, and a number of people are using it to successfully run an Identity Provider with Tomcat 7. With this additional JAR, you can use all the features of the Identity Provider with Tomcat 7. As noted, it is not supported by the Shibboleth Consortium team, but Unicon responds to questions on the Shibboleth Users list.

Required Configuration Changes

Endorse Xerces and Xalan by creating the directory TOMCAT_HOME/endorsed and copy the .jar files included in the IdP source endorsed directory into the newly created directory.
- Note: Tomcat 6 no longer includes an endorsed directory in most distributions, but by default will load and endorse libraries located in $TOMCAT_HOME/endorsed if .jars are placed at that path. You can also determine or set the location of the endorsed directory by searching your Tomcat launch scripts for -Djava.endorsed.dirs=.
  Hint for CentOS 6: you may want to add "JAVA_ENDORSED_DIRS=$CATALINA_HOME/endorsed" to /usr/share/tomcat6/conf/tomcat6.conf
Add the following parameters to the JAVA_OPTS environment variable (all ### is the amount of memory in megabytes to allow for the option):
- -Xmx###m - this is the maximum amount of memory that Tomcat may use, at least 512M is recommended
- -XX:MaxPermSize=128m - (Sun JVM specific option) the maximum amount of memory allowed for the permanent generation object space
Under Windows, the JAVA_OPTS variables are set via the "Manage Tomcat" application in the "Java" Tab.

Recommended Configuration Changes

Limit the allowed size of POST submissions to any HTTP or AJP connectors (including the SOAP connector below) by adding the maxPostSize attribute. A size of 200K (204800) is a reasonable choice.

Supporting SOAP Endpoints

For Tomcat 6, download tomcat6-dta-ssl-1.0.0.jar (asc) in to TOMCAT_HOME/lib/, or to use Tomcat 7 with the unofficial Unicon component, download tomcat7-1.1.jar. Shibboleth IdPs and SP communicate directly, as opposed to sending messages via the user's browser, during certain operations (Attribute Query, Artifact Resolution, and some forms of Logout). In order to support these request the IdP needs an additional port (called a Connector within the Tomcat configuration), distinct from the one used by the user (because they have different, mutually exclusive, security requirements).

Add the following connector definition to Tomcat's TOMCAT_HOME/conf/server.xml file for tomcat 6:

<Connector port="8443"
           protocol="org.apache.coyote.http11.Http11Protocol"
           SSLImplementation="edu.internet2.middleware.security.tomcat6.DelegateToApplicationJSSEImplementation"
           scheme="https"
           maxPostSize="204800"
           SSLEnabled="true"
           clientAuth="want"
           keystoreFile="IDP_HOME/credentials/idp.jks"
           keystorePass="PASSWORD" />

or this one for tomcat 7:

    <Connector port="8443"
               protocol="org.apache.coyote.http11.Http11Protocol"
               sslImplementationName="edu.internet2.middleware.security.tomcat7.DelegateToApplicationJSSEImplementation"
               SSLEnabled="true"
               scheme="https"
               secure="true"
               maxPostSize="204800"
               clientAuth="want"
               keystoreFile="IDP_HOME/credentials/idp.jks"
               keystorePass="PASSWORD"
               sslProtocol="TLS" />

Replace IDP_HOME with the IdP home directory entered during installation.
Replace PASSWORD with the password for the IdP key entered during installation.

Using a Context Deployment Fragment

If you use this deployment method you do not need to do anything additional to deploy your application.

Normally you deploy web applications to Tomcat by copying the WAR file into the Tomcat webapps/. However, when you do this Tomcat will explode the war (giving you idp.war and idp/ within webapps/) and then cache another version of the application in work/Catalina/localhost/. This can lead to cases where you copy a new WAR into place but Tomcat continues to use the older version.

To address this, it is recommended that you use a context deployment fragment, which is just a small bit of XML that tells Tomcat where to get the WAR and provides some properties used when Tomcat load the application. This approach will also prevent those times when you create a new WAR and forget to copy it into Tomcat as this makes Tomcat load the war from IDP_HOME/war/ where the installer places it.

Create the file TOMCAT_HOME/conf/Catalina/localhost/idp.xml and place the following content in it:
```
<Context docBase="IDP_HOME/war/idp.war"
         privileged="true"
         antiResourceLocking="false"
         antiJARLocking="false"
         unpackWAR="false"
         swallowOutput="true" />
```
You might also want to add cookies="false" to the above Context Deployment Fragment, to prevent Tomcat from settting HTTP Cookies e.g. on MDUI Logos hosted at the IdP webserver, which would trigger Third Party Cookie warnings in some HTTP User Agents.
Replacing IDP_HOME with your IdP's home directory.

IdPApacheTomcatPrepare