Welcome

Enabling SSL with Client Authentication in Tomcat

It is very common to enable SSL only with server authentication, because it is required from SSL specification. However, it is not so common to activate client authentication as it is optional.

Enabling SSL is a server dependent process. I first give a rough overview of this process step by step and then explain each one in detail with examples using Tomcat.

  • First configure Connector definition in tomcat server.xml file.
  • Create a certificate with alias tomcat for server authentication and place it in a keystore that will be accessed by tomcat
  • Create a trust keystore that will be used to keep trusted certificate entry which will be used during client authentication.
  • Create a client certificate that will be used for client authentication.

That’s all! It is time to now go over each step in detail.

As a first step, we have to configure Connector definition in server.xml file. By default server.xml file contains a Connector definition for SSL, but it is commented, and we need to add some other attributes to it. We can start with commenting out that connector definition.

<Connector port="8443" 
               maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
               enableLookups="false" disableUploadTimeout="true"
               acceptCount="100" debug="0" scheme="https" secure="true"
               clientAuth="true" sslProtocol="TLS" />

We have to convert clientAuth attribute’s value to true to enable client authentication, otherwise our server will not ask a client certificate. Then we specify our keystore file location, in which out server’s certificate will be kept, and its password.


keystoreFile=”/keystores/server.keystore”    keystorePass=”secret”

By default tomcat looks for server certificate in a keystore that is in user’s home directory with default password “changeit”.

In addition to specifying keystore location for server certificate, we need also to specify tomcat where to look for validating client certificates.


truststoreFile=”/keystores/trust.keystore”

We can use same password for both of the keystore files and specifying only one’s is enough. Providing truststoreFile in connector definition is important, otherwise internet explorer will not be able to display available certificates that can be used for client authetication.

Second step is creating necessary certificates both for server and client. We need a trusted certificate authority to create and validate those certificates. I used Microsoft Certification Authority for this step. It is also possible to create self signed server certificate using java keytool, and use it in server authentication, but for client authentication we need to create a personal client certificate and this is not possible with keytool.
We can download CA certificate from MS Certification Authority via its web interface,and then install it in our trust and server keystores. For example let say ca.cer is our downloaded CA certificate file;


keytool –import –trustcacerts –alias ca –file ca.cer –keystore /keystores/server.keystore –storepass secret
keytool –import –trustcacerts –alias ca –file ca.cer –keystore /keystores/trust.keystore –storepass secret

keytool –genkey –alias tomcat –keystore /keystores/server.keystore –storepass secret

This will generate public-private key pair that will be used for server authentication. It is important to make key and keystore passwords same, otherwise tomcat will not be able to access certificate. Later we create a certification request using this generated key pair.


keytool –certreq –alias tomcat –file /keystores/tomcat.req –keystore /keystores/server.keystore –storepass secret

We use this certification request to create a certificate from Certification Authority, again via its web interface. When our certificate is ready, we need to import it into our keystore. Let say our generated certificate is in file tomcat.cer;


keytool –import –alias tomcat –file /keystore/tomcat.cer –keystore /keystores/server.keystore –storepass secret

imports certificate that will be used for server authentication.

We also need to create a client certificate that will be used to authenticate our client/user. We create it via Certification Authority. We make a certification request. When CA issues a certificate for us, we need to install it using Internet Explorer, accessing through web interface of Certification Authority. Internet Explorer keeps our client certificate’s private key  in a safe place, that is local to our client’s machine, so this certificate will be working only from our client’s machine from which we make certification request.

One important key note here: Internet Explorer will not display client certificate selection dialog, if there is no valid or there is only one valid client certificate installed in the client machine. If we want to display this dialog, even for those cases, we need to configure it using Internet Options>Security Settings window, by disabling “Don’t prompt for client certificate selection when no certificates or only one certificate exists”. Internet Explorer determines valid client certificates via tomcat’s trusted certificate located in trustkeystore. If we don’t provide trustkeystore for Tomcat, Internet Explorer will not be able to show our valid client certifices in its certificate selection dialog.

Finally it is time to give a try for our SSL configuration: https://localhost:8443.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.