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 not yet officially supported by the Shibboleth project)
Java 6 or later (see additional notes in IdPInstall)

Required Configuration Changes

Add the following parameters to the JAVA_OPTS environment variable (all ### is the amount of memory in megabytes to allow for the option):
- -XX:+UseG1GC - this enables a garbage collector that reduces the memory requirements needed for larger metadata files
- -Xmx1500m - this is the maximum amount of memory that Tomcat may use, at least 1.5G is recommended for larger (>25M) metadata files
- -XX:MaxPermSize=128m - (Oracle Java 6/7 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.
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 about 100K (100000) is a reasonable choice.

Supporting SOAP Endpoints

Most new deployments without legacy needs will not need to support back-channel SOAP communication. The most common case requiring this feature is support for legacy Shibboleth SPs using SAML 1.1 that perform attribute queries using SOAP.

If you do need this support, these connections require special security properties which are not appropriate for user-facing/browser use. Therefore an additional endpoint must be configured.

For Tomcat 6, download tomcat6-dta-ssl-1.1.0.jar (asc) in to TOMCAT_HOME/lib/, or to use Tomcat 7 with the unofficial Unicon component, download tomcat7-1.1.jar.

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="100000"
           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="100000"
               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 (replacing IDP_HOME with your IdP's home directory):
<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.