The Shibboleth IdP V4 software has reached its End of Life and is no longer supported. This documentation is available for historical purposes only. See the IDP5 wiki space for current documentation on the supported version.

SystemTLSTrustConfiguration

Owned by Scott Cantor
Feb 08, 2019

It is a recommended best practice to define a JVM system trust store that contains the minimum set of trusted CA certificates required for the IdP to function. Most or all of the IdP's features support explicit configuration of trust material on a per-component/feature basis and we strongly recommend that approach. Where a system-level set is necessary, it should be minimized (ideally empty) to prevent accidental use of unexpected trust anchors.

Planning

In order to create a minimal trust store, you must first understand your system dependencies. Identify all hosts to which the IdP makes outbound TLS connections that are not covered by explicit IdP configuration, then identify the root CAs of the certificate chain presented by each host. Create a PEM-encoded certificate for every CA certificate and place them all in an otherwise empty filesystem directory.

Creating a Minimal System Trust Store

Use this Bash script to generate a PKCS#12 trust store. The only requirement for the script is a functional JDK with the keytool utility on the path.

Sample script usage
marvin@petros:~$ ls TrustedCerts/
vtc1sca.pem	vtgrootca.pem	vtmwca.pem	vtuca.pem
vtgqsca.pem	vtgsca.pem	vtrootca.pem
marvin@petros:~$ gen-truststore.sh TrustedCerts/ $IDP_HOME/conf/minimal-system-trust.p12
Processing TrustedCerts/vtc1sca.pem
Certificate was added to keystore
Processing TrustedCerts/vtgqsca.pem
Certificate was added to keystore
Processing TrustedCerts/vtgrootca.pem
Certificate was added to keystore
Processing TrustedCerts/vtgsca.pem
Certificate was added to keystore
Processing TrustedCerts/vtmwca.pem
Certificate was added to keystore
Processing TrustedCerts/vtrootca.pem
Certificate was added to keystore
Processing TrustedCerts/vtuca.pem
Certificate was added to keystore
Truststore created with trusted certificates:

Keystore type: PKCS12
Keystore provider: SunJSSE

Your keystore contains 7 entries

vtc1sca, Dec 14, 2018, trustedCertEntry,
Certificate fingerprint (SHA1): E4:6F:B9:58:B7:85:CB:DB:93:B6:86:5B:F8:A9:83:7A:B0:B7:D0:27
vtgqsca, Dec 14, 2018, trustedCertEntry,
Certificate fingerprint (SHA1): 8C:D1:CD:9E:24:3D:7C:15:4C:EC:FA:B8:C1:EA:AA:85:C1:48:DB:11
vtgrootca, Dec 14, 2018, trustedCertEntry,
Certificate fingerprint (SHA1): E0:95:6F:11:6F:59:A0:99:79:AB:38:2F:3C:16:16:A9:9A:DB:83:AE
vtgsca, Dec 14, 2018, trustedCertEntry,
Certificate fingerprint (SHA1): 10:3C:2B:C0:02:C0:4F:F9:5E:D4:85:CE:CD:F8:85:34:6A:63:DC:AB
vtmwca, Dec 14, 2018, trustedCertEntry,
Certificate fingerprint (SHA1): 95:88:44:22:CE:30:4E:62:B7:4C:83:5F:3B:05:24:0C:BC:D8:3A:83
vtrootca, Dec 14, 2018, trustedCertEntry,
Certificate fingerprint (SHA1): AF:6F:EB:42:FA:2F:E4:A2:6E:9F:7F:B5:B5:FF:3A:BC:13:C6:0D:81
vtuca, Dec 14, 2018, trustedCertEntry,
Certificate fingerprint (SHA1): AC:01:D0:4E:23:08:93:BC:BA:F4:50:CA:15:58:2C:3A:88:40:B7:B7

Using the Minimal System Trust Store

The key configuration point is to set the following system properties of the Java process that starts the servlet container:

-Djavax.net.ssl.trustStore=$IDP_HOME/conf/minimal-system-trust.p12
-Djavax.net.ssl.trustStoreType=PKCS12
-Djavax.net.ssl.trustStorePassword=password

See the JSSE Reference Guide for a thorough description of these properties. The password on the PKCS#12 file is required by convention but provides no security, thus the insecure string "password" used by the generator script. The process of setting JVM system properties varies with servlet container platform and is discussed in subsequent sections.

Configuring Jetty for Minimal System Trust

Add the following lines to the file /etc/default/jetty (create it if necessary) and replace the path to your IdP home directory with the actual path:

IDP_HOME="/path/to/idp.home"
JAVA_OPTIONS="-Djavax.net.ssl.trustStore=$IDP_HOME/conf/minimal-system-trust.p12 -Djavax.net.ssl.trustStoreType=PKCS12 -Djavax.net.ssl.trustStorePassword=password"

If jetty is running as a Unix service (e.g. service jetty start) or otherwise using the jetty.sh startup script, then there is nothing further required. If jetty is started using start.jar directly, simply source the file above prior to running Java:

source /etc/default/jetty
java -jar $JETTY_HOME/start.jar

Configuring Tomcat for Minimal System Trust

Add the following lines to the file $CATALINA_BASE/conf/catalina.properties:

javax.net.ssl.trustStore=/path/to/your/idp.home/conf/minimal-system-trust.p12
javax.net.ssl.trustStoreType=PKCS12
javax.net.ssl.trustStorePassword=password