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. 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:B7Using 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=passwordSee 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:
Configuring Tomcat for Minimal System Trust
Add the following lines to the file $CATALINA_BASE/conf/catalina.properties:
Â