Preparing Apache Tomcat for the Shibboleth Identity Provider
- 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:
or this one for tomcat 7:
IDP_HOME with the IdP home directory entered during installation.
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
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):
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.