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.

Please note though, that there are some SPs in the federation that cannot inter-operate with IdPs with self-signed trust fabric certificates. If the IdP must inter-operate with one of these SPs then you should use a federation-recognised CA certificate for the federation trust fabric. In that case you should configure the recognised CA certificate in both the Tomcat connectors. Please consult the federation support team if in doubt.

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 federation-qualified 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

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 follows: 

 
<Connector port="443"
           protocol="org.apache.coyote.http11.Http11Protocol"
           scheme="https"
           secure="true"
           SSLEnabled="true"
           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"
           clientAuth="true"
           keystoreFile="/opt/shibboleth-idp/credentials/idp.jks"
           keystorePass="password1"/>