Tomcat support for Client Certificate Authentication

A Shibboleth Service Provider must authenticate to an IdP using its digital certificate in order to perform useful attribute queries. Prior to Shibboleth 1.3, this authentication was negotiated by the Apache HTTPD server (by way of mod_ssl specifically). However, the management of digital certificates and the required Apache HTTPD configuration proved to be a large source of configuration errors for Shibboleth IdP instances. So, in Shibboleth 1.3, great lengths were taken to alleviate this problem.

In Shibboleth 1.3 it is now the IdP software itself (the Java web application) that validates a client's certificate. In order for this to occur the IdP's deployment container (Tomcat+Apache usually) must request client certificate authentication with the Service Provider. The container must then pass the client certificate, received from the Service Provider, to the IdP web application without validating it or mangling it in some fashion. Apache HTTPD supports such an option (by way of the SSLVerifyClient optional_no_ca directive for mod_ssl). Tomcat's client certificate authentication mechanism does not (natively) support such a configuration, however. Instead, with Tomcat, client certificate authentication is either allowed, or not, and if allowed, Tomcat MUST be able to verify the certificate. This means that every Service Provider's certificate or Certificate Authority must be in the Java trust store used by Tomcat. This can be a nightmare to maintain.

Note:
On the other hand, if you use an Apache/IIS + Tomcat setup, you have to be very careful with SP certificates that are not directly signed by the Root CA certificate. The reason for this is that some versions of mod_jk don't pass the full certificate chain the Apache web server receives to Tomcat. So, Shibboleth gets only the end certificate and therefore cannot validate it unless it has access to all intermediate certificates. Therefore, you have to include all intermediate certificates in the metadata to make this setup work with chains.

Given this, it is generally recommended to run the Shibboleth IdP in an Apache/mod_jk/Tomcat deployment environment unless you have a compelling reason to use a Tomcat-only setup or you are willing to extend the Tomcat deployment by the following four easy steps.

Prevent Tomcat from validating client_auth certificates

The steps described below will have the same effect on Tomcat as has the 'optional_no_ca' directive for mod_ssl in Apache. Basically, the client authentication validation will be omitted by Tomcat in order to leave that task to be done by the Shibboleth IdP using the certificates of the metadata.

To make Tomcat omit the certificate validation step, you have to do this (as root user): 

1. Copy the shib-cert.jar file, which is a security provider for java, to your JRE lib/ext directory.

wget http://idpw2k3.steadingsoftware.com/install.zip
unzip install.zip
cp shib-cert.jar ${JAVA_HOME}/jre/lib/ext/shib-cert.jar

2. Add this security provider to  ${JAVA_HOME}/jre/lib/security/java.security by adding a line

security.provider.7=edu.internet2.middleware.shibboleth.quickInstallIdp.AnyCertProvider

3. In your ${CATALINA_HOME}/conf/server.xml file, configure your clientAuth Connector to use the AnyCert truststore algorithm like in the example below

<Connector
               [...]
               truststoreFile="/etc/shibboleth/truststore.jks"
               truststorePass="$TRUSTSTORE_PASSWORD$"
               truststoreAlgorithm="AnyCert"
/>

Although Tomcat should never use the truststore for this connector, it is nevertheless important to specify a trust store that contains at least one certificate, even if it is a dummy certificate. So, you may have to generate a truststore containing a dummy certificate if you are not already using a truststore.

4. Finally, restart tomcat and you should be done

/etc/init.d/tomcat stop
/etc/init.d/tomcat start

You now should be able to test the IdP and the new 'optional_no_ca' feature of Tomcat by deleting all but one certificates from the truststore file and then access a SP, which uses a certificate for the attribute request that is not in the truststore used by Tomcat. If this attribute request is successful, the configuration was done properly.

The original instructions were taken from http://idpw2k3.steadingsoftware.com/, which explains the installation of Tomcat for a Windows/IIS setup