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
- Scott Cantor
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.
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