Tomcat Configuration (without Apache)

If Apache is not being used to proxy the IdP then you must ensure that Tomcat has a connector configured in the conf/server.xml file (in the Tomcat installation directory) for each of ports 443 and 8443 as described below. You should first ensure you have followed the Shibboleth 2.x instructions for preparing Tomcat unless you are using the Windows installer.

Please note that if you are using the Windows installer it will generate a working configuration for you in server.xml that might not look exactly like the one below. In that case there is no need to change it, except to change the values of keystoreFile and keystorePass and add keystoreType="PKCS12" to the port 443 connector in server.xml so that it refers to the PKCS12 file containing your CA certificate and private key, as described below. You should not need to make any changes to the port 8443 connector.

The federation now recommends that a self-signed certificate is used for an IdP's federation trust fabric certificate. The Shibboleth IdP's installation script generates a suitable self-signed certificate, which is configured in the <security:Credential> element in the relying-party.xml file. It also creates a Java keystore file called idp.jks, which contains the self-signed certificate and private key; you should edit the Tomcat port 8443 Connector configuration to refer to this keystore file, as below. An SSL certificate must be used as the browser-facing certificate to protect the port 443 SSL "endpoint" of the IdP (the URL used to access the IdP by browsers), and this is configured in the Tomcat port 443 Connector configuration as below.

Tomcat cannot use certificate files directly, but instead uses Java keystores. You will therefore need to create a Java keystore file containing your browser-facing certificate, its corresponding private key file, and the intermediate certificate file supplied by the certification authority. Without going into detail, a Java keystore is a type of file that can contain a private key and a certificate, and a CA's intermediate file if there is one. Here we recommend use of the PKCS12 format, because then you can use the OpenSSL tool to generate it, which is available for most platforms, and we have a straightforward recipe for doing this, as documented below.

If you have not yet obtained your browser-facing certificate then please read the documentation on how to acquire a CA certificate. If you already have a CA certificate then the CA should also have sent you their intermediate certificate, which may actually be a "bundle" of several certificates concatenated together. The intermediate certificate in the command given below has a .pem filename extension, but yours might not be like that. The command should still work for you, however. Please contact the federation support team if you have difficulties.

Please note that you should not include the CA's root certificate in the intermediate certificate bundle, because some versions of SSL may not verify the certificate chain if the root certificate is present.

Creating the PKCS12 keystore file for the CA certificate

To create a PKCS12 keystore file ssl-certificate.pkcs12 given an existing private key file ssl-private-key.key, certificate file ssl-certificate.crt and the CA's intermediate certificate file intermediate.pem, where all filenames are relative to the current directory or folder, you can use the following OpenSSL command. You can change the filenames as appropriate for your needs:

 
 openssl pkcs12 -export -in ssl-certificate.crt -inkey ssl-private-key.key \
   -certfile intermediate.pem -out ssl-certificate.pkcs12

The resulting keystore file ssl-certificate.pkcs12 contains the private key, the certificate and the intermediate certificate. Nothing will be overwritten by this command unless you already have a file called ssl-certificate.pkcs12.

Please note that the keystore file ssl-certificate.pkcs12 should be kept secret and definitely not emailed to anybody, because it contains your private key. All the security precautions that apply to your private key file also apply to your keystore file.

Of course, if you are familiar with Java keystores then you can use your preferred mechanism for creating the keystore file.

The IdP configuration in server.xml

Please see the Shibboleth documentation for the recommended Tomcat configuration. Tomcat 7 is now supported by a third party library, and we and others have verified that this also works with Tomcat 8. We provide baseline configurations below for Tomcat 6, 7 and 8, but you should also check the Shibboleth documentation.

To configure the IdP to use the ssl-certificate.pkcs12 keystore you will also need to specify keystoreType="PKCS12" and change the values of keystoreFile and keystorePass in the Tomcat server.xml file, which is normally in the Tomcat conf subdirectory. The resulting Tomcat connector configuration, assuming your IdP installation directory is /opt/shibboleth-idp, is as below.

Please note the following points:

• Java 6 and versions lower do not support TLSv1.1 or TLSv1.2. Java 7 or Java 8 is recommended for better security, but please ensure you are aware of these issues concerning scripted attributes and Java 8 before upgrading. If in doubt then upgrade to Java 7.
• A few Java-based SPs use the SSLv2Hello protocol in the SSL handshake, which requires it be enabled at the IdP end. To support interoperation with such SPs you may need to add SSLv2Hello to the list of protocols in the protocols directive on port 8443. Please contact the federation support team if you need advice about this.
• In Java 8 you can specify secure Diffie-Hellman parameters using jdk.tls.ephemeralDHKeySize=2048. This is a Java property that can normally be set by means of the CATALINA_OPTS variable:
  
  export CATALINA_OPTS="$CATALINA_OPTS -Djdk.tls.ephemeralDHKeySize=2048"
• We have not specified a cipher suite configuration, as the cipher suites available depend on your version of Tomcat and Java. You can and should improve your TLS security by specifying secure cipher suites. The SSL Labs website provides a very useful tool for analysing your TLS configuration; it reports the list of cipher suites it detects as being supported and flags up any that are insecure or weak.
  
  A good starting point is to test your host with SSL labs with no cipher suites specified in your port 443 Connector. Then take the list of cipher suites it reports and remove the ones that are insecure or weak, add the list of secure suites using the ciphers directive to your port 443 Connector, and test again.
  
  https://www.ssllabs.com/ssltest/
• With Tomcat 8 and Java 8 you can achieve still better security and interoperability using the configuration directive useServerCipherSuitesOrder="true" in the appropriate Connector and specifying cipher suites in order of preference. The TLS_ECDHE ciphers should be first in the ordering, then the TLS_DHE ciphers, then the TLS_RSA ciphers, then any others that remain from your list of secure ciphers.
• We would expect that a good working configuration of protocols and cipher suites for port 443 will usually also be appropriate for port 8443.
• The recommended configurations given below do not support Internet Explorer 6 on Windows XP.
• If you need to interoperate with Internet Explorer 8 on Windows XP then you will need SSL_RSA_WITH_3DES_EDE_CBC_SHA in your ciphers list. SSL labs detects this as TLS_RSA_WITH_3DES_EDE_CBC_SHA but it has to be specified as SSL_RSA_WITH_3DES_EDE_CBC_SHA.

Tomcat 7 and 8

 
<Connector port="443"
           protocol="org.apache.coyote.http11.Http11Protocol"
           scheme="https"
           secure="true"
           SSLEnabled="true"
           sslEnabledProtocols="TLSv1, TLSv1.1, TLSv1.2"
           keystoreType="PKCS12"
           keystoreFile="/opt/shibboleth-idp/credentials/ssl-certificate.pkcs12"
           keystorePass="password2"/>

<Connector port="8443"
           protocol="org.apache.coyote.http11.Http11Protocol"
           sslImplementationName=
               "edu.internet2.middleware.security.tomcat7.DelegateToApplicationJSSEImplementation"
           scheme="https"
           SSLEnabled="true"
           sslEnabledProtocols="TLSv1, TLSv1.1, TLSv1.2"
           clientAuth="true"
           keystoreFile="/opt/shibboleth-idp/credentials/idp.jks"
           keystorePass="password1"/>

Tomcat 6

If you find that the configuration below does not work for you then you may need to substitute the string sslEnabledProtocols or sslProtocols in place of protocols in the configuration for each connector. Some form of this directive is required to ensure that the insecure SSLv3 protocol is not used.

 
<Connector port="443"
           protocol="org.apache.coyote.http11.Http11Protocol"
           scheme="https"
           secure="true"
           SSLEnabled="true"
           protocols="TLSv1, TLSv1.1, TLSv1.2"
           keystoreType="PKCS12"
           keystoreFile="/opt/shibboleth-idp/credentials/ssl-certificate.pkcs12"
           keystorePass="password2"/>

<Connector port="8443"
           protocol="org.apache.coyote.http11.Http11Protocol"
           SSLImplementation=
               "edu.internet2.middleware.security.tomcat6.DelegateToApplicationJSSEImplementation"
           scheme="https"
           SSLEnabled="true"
           protocols="TLSv1, TLSv1.1, TLSv1.2"
           clientAuth="true"
           keystoreFile="/opt/shibboleth-idp/credentials/idp.jks"
           keystorePass="password1"/>