This page describes a Tomcat setup for SSL Client Authentication with fallback to FORM authentication. This is not for using FORM based authentication over a simple SSL channel - you do not need SSL client authentication for that.
Note: Tested with Tomcat 5.5.17 and 5.5.20
SSL Client Authentication (sometimes also known as "Client Certificate" authentication) uses the SSL protocol to authenticate clients based on a X509 Certificate. Normally this is accomlished by configuring SSL in Tomcat, and then configuring the Web Application's security descriptor to use "CLIENT-CERT" as the auth-method in the login-config section.
We found that we wanted to implement 2 levels of security - client authentication based on SSL certificates for serious security, but FORM based login as a fallback option. This requirement can exist for a number of reasons:
- for customers who do not want to make use of certificates
- for when the customer certificate expires
- to permit customers to log in for the first time without a certificate
- to allow different "user-levels" - high security vs. low security, with different functions available
- etc...
In trying to implement this, we found the only "standard conformant" solution was to install the web application multiple times with different authentication configurations. This solution was very unsatisfactory for us, as it leads to a duplication of services, and the serives are accessible under different URLs/Ports depending on the desired security level. That just wasn't what we wanted.
So the following solution, unfortunately, is not standards-conformant. This is because the J2EE standard, while deferring authentication to the container, specifies the authentication method in the webapplication deployment descriptor (web.xml). There, only one login-config section is allowed, which counts for the whole application. It does not permit you to configure a fallback login method.
Setup
So, to get the fallback login working you will need the following:
- Tomcat Installation
- Your Webapplication
The Java Class ["SSLWithFormFallbackAuthenticator"] (download from here)
- Server Certificate & Private Key
- Client Certificate & Private Key
- Certification Authority Public Certificates
It is assumed that your web-application is working, and you are currently using FORM based authentication. Your login config in your web.xml deployment descriptor should therefore look something like this:
<pre>
<login-config>
<auth-method>FORM</auth-method>
<form-login-config>
<form-login-page>/pub/login.jsp</form-login-page>
<form-error-page>/pub/loginerror.jsp</form-error-page>
</form-login-config>
</login-config>
</pre>
It is further assumed that your web-application contains at least one protected page, requiring authentication.
Basic SSL Setup
First, setup SSL in Tomcat, as described in: http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html
Make sure basic SSL is working, without client authentication. You can test this using your browser. While you are at it, add the server's certification authority to your Browser's list of trusted certificates, if it is not there already. You should be able to access your application normally, but via the https (SSL) protocol. If you access a protected page, you should be prompted for a login using the FORM login you configured.
SSL Client Authentication
In the tomcat server.xml file, configure the server to use client authentication:
<pre>
<Connector
port="8443" minProcessors="5" maxProcessors="75"
enableLookups="true" disableUploadTimeout="true"
acceptCount="100" debug="0" scheme="https" secure="true";
clientAuth="want" sslProtocol="TLS"
keystoreFile="/etc/mykeystore.jks" keystorePass="changeit"
truststoreFile="/etc/mytruststore.jks" truststorePass="changeit"/>
</pre>
Note the use of clientAuth="want" to request a certificate, but not fail if none is presented.
Testing Client Authentication
Now change your login config to