Tomcat 10.1

These pages are examples and do not reflect any normative requirements or assumptions on the part of the IdP software and may be a mix of suggestions from both the project team and deployers. You should take any of this advice with a grain of local salt and consider general security/deployment considerations appropriate to the use of web software in your local environment.

The official information about containers and versions we support is solely maintained on the SystemRequirements page. If you wish to operate without complete responsibility for your Java servlet container, you may consider the Windows package we provide that includes an embedded container.

1 CATALINA_HOME and CATALINA_BASE
2 Example CATALINA_BASE
3 Version Notes
4 Required Configuration
5 Recommended Configuration
- 5.1 Logging
- 5.2 Disable Directory Indexing
- 5.3 TLS Ciphers
- 5.4 Jar Scanner Filter

`CATALINA_HOME` and `CATALINA_BASE`

CATALINA_HOME refers to the directory of the “binary” Tomcat distribution.
Example : /opt/apache-tomcat-$version
Do not change Tomcat configuration files in CATALINA_HOME.
CATALINA_HOME should not be a subdirectory of idp.home.
CATALINA_BASE refers to the directory containing Tomcat configuration files to run the IdP.
Example : /opt/tomcat-base-idp
Make changes to Tomcat configuration files in CATALINA_BASE only.
All paths are relative to CATALINA_BASE unless otherwise noted.

For more information :

“Advanced Configuration - Multiple Tomcat Instances” in RUNNING.txt
Tomcat documentation introduction

Example `CATALINA_BASE`

An example CATALINA_BASE directory for the IdP is available in our git repository here : java-idp-tomcat-base

The 10.1 branch contains Tomcat configuration files for Tomcat version 10.1

git clone https://git.shibboleth.net/git/java-idp-tomcat-base
cd java-idp-tomcat-base
git checkout 10.1

Version Notes

The latest stable version of Tomcat 10.1 should be used.

Tomcat configuration reference

Required Configuration

The bulk of the configuration is established by setting properties in conf/catalina.properties.

Most of the properties are defined by Tomcat. The properties at the beginning are specific to the IdP [ TODO and are prefixed with idp.tomcat ].

An alternative to setting properties in conf/catalina.properties is to set system properties in bin/setenv.sh. However, properties set in bin/setenv.sh will be visible to command line utilities such as ps which is inadvisable for passwords.

JSTL Support

Small portions of the IdP like the status page may depend on the JSTL library, which is not included in Tomcat by default. Our example tomcat-base artifact includes copies of those libaries (i.e., https://git.shibboleth.net/view/?p=java-idp-tomcat-base.git;a=tree;f=tomcat-base/lib;h=b5fccf2aaefee18d51020a6a221e6059ad668e17;hb=refs/heads/10.1).

Configure `idp.home` and JVM Settings

File: bin/setenv.sh

Tomcat documentation : RUNNING.txt

The idp.home system property must be set in bin/setenv.sh if it is used in the Context descriptor idp.xml described below.

An alternative is to define idp.home in the Context descriptor idp.xml only and not in bin/setenv.sh.

setenv.sh

#!/bin/sh

export "CATALINA_OPTS=$CATALINA_OPTS -Didp.home=/opt/shibboleth-idp"

TODO JVM options etc.

Configure HTTP/HTTPS Connectors

File(s): conf/server.xml, conf/catalina.properties, credentials/idp-userfacing.p12

The basic HTTP/HTTPS port, address, etc. configuration can be handled within conf/server.xml and conf/catalina.properties.

The example below shows some of the basic properties you can use to configure networking and TLS credentials.

One challenge remains that if you want to use standard ports, you would need to pick one of these options to avoid running as root:

See How to run Tomcat without root privileges
Use a port forwarding approach (load balancer, iptables rules, etc).
Use POSIX capabilities to allow use of priviledged ports by an unpriviledged process, e.g. when using systemd by setting AmbientCapabilities=CAP_NET_BIND_SERVICE

`conf/catalina.properties`

# HTTP connector
# Allows use of default IdP command line tools.
tomcat.http.host=127.0.0.1
tomcat.http.port=80

# The HTTPS connector
# The interface to listen on. To listen on all interfaces, set tomcat.host = 0.0.0.0
tomcat.https.host=0.0.0.0
tomcat.https.port=443
tomcat.https.certificateKeystoreFile=credentials/idp-userfacing.p12
tomcat.https.certificateKeystorePassword=changeit

`conf/server.xml`

HTTP

HTTPS

`credentials/idp-userfacing.p12`

The TLS credential relies on a PKCS12 file containing the X.509 certificate and private key used to secure the HTTPS channel that users access during authentication and other browser-based message exchanges involving the IdP. This is generally the one you get from a browser-compatible CA, and the example shows it being loaded from credentials/idp-userfacing.p12.

A variety of other networking properties can be set based on the Tomcat HTTP and HTTPS connectors; refer to their documentation.

Configure IdP Context Container

File: conf/Catalina/localhost/idp.xml

In order to deploy the IdP, Tomcat must be informed of the location of the IdP WAR file via a Context descriptor.

This Context descriptor assumes idp.home is a system property set in bin/setenv.sh.

The Context Path will be /idp since the Context descriptor file name is idp.xml.

conf/Catalina/localhost/idp.xml

See the Context configuration documentation for more information.

TODO document attributes

Recommended Configuration

Logging

File: conf/logging.properties

By default Tomcat logs to the logs/ directory.

See the documentation for more information.

Disable Directory Indexing

Listing directories is disabled by default. This is configured via the listings initialization parameter in conf/web.xml.

TLS Ciphers

As with all web servers, it's a challenge to stay on top of all the best practices related to TLS/SSL versions, ciphers, etc. It's usually best to be in a position to make adjustments to this quickly, and test after upgrades.

Tomcat documents a way to adjust this sort of thing here. The basic procedure is to customize the ciphers attribute for the HTTPS connector in conf/server.xml via . You should do some testing against SSL Labs or some other source of information to evaluate what the defaults look like and make any adjustments you think are warranted.

Jar Scanner Filter

Tomcat scans JARs for TLDs at startup. JARs for the IdP and the OIDC OP plugin are skipped because they have been added to tomcat.util.scan.StandardJarScanFilter.jarsToSkip in conf/catalina.properties.