Page History

...

• Tomcat Installation
• Your Webapplication

• Wiki Markup
  The Java Class \["SSLWithFormFallbackAuthenticator"\] (download from here)

• Server Certificate & Private Key
• Client Certificate & Private Key
• Certification Authority Public Certificates
• Working authentication realm
  

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, and that the login currently works using your FORM based login with an appropriate Login Realm.

Basic SSL Setup

First, setup SSL in Tomcat, as described in: http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html

...

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.

Configure your Realm to accept the client certificate. Depending on which realm you are using, you will need to add a user for the certificate in different ways. The default Tomcat Realms use the "SubjectDN" field of the certificate as a "username" to look up the user.

Testing Client Authentication

Fire up your browser and install the client certificate and private key in your certificate store.

Now change your auth-method from "FROM" to "CLIENT-CERT" and restart/redeploy your web-app. If you access your protected page you should now be prompted for a certificate by your browser. Select the installed certificate. If everything was configured correctly you should be authenticated based on your certificate, and taken to the protected page.

If things go wrong, here's some places to look:

TO BE CONTINUED TOMORROW!Now change your login config to