Setting up SSL on Tomcat

Requirement: Set up SSL on local Tomcat instance, with client certificate required, so that HTTPS transport can be checked on Axis2 web service calls.  Assume SoapUI can be the client for testing.

There are a fair number of documents out there about creating certificates, etc. but I didn’t see anything like this. There is some good basic info on SSL on Tomcat here.

Generating Key Pairs

1. Open a command prompt.
2. Navigate to %JAVA_HOME%/bin
3. Type the following (Note: Use whatever passwords you want, but make sure keypass and storepass are the same.):

   keytool -genkey -alias tomcatSSL –keyalg \"RSA\" -keypass password -keystore localDevKeystore.bin -storepass password

4. Fill in the prompts.  The only critical one is the first one.  Make sure you enter whatever hostname you plan to use to access local Tomcat with.  For example:

   What is your first and last name? localhost

5. You’ll be asked to confirm the FQN matching the data you just entered.  Type yes
6. Move the localDevKeystore.bin file that was just created from %JAVA_HOME%/bin to %TOMCAT_HOME%/conf/certs

Insert keys in Java keystore

In order to use the certificates you generated, they need to be available to the JRE of Tomcat.  Basically, you have to add the keypair (at least the server portion) you generated to the %JRE_HOME%/lib/security/cacerts file.  You can use the key tool command line program to add certificates, but I’ve found the IBM KeyMan utility to be a very useful tool.  Essentially, it’s a GUI front end to key tool, which is nice because key tool can be finicky and require you to know more than you do about the certificates being used.

Configuring Axis2

1. 1. Open %TOMCAT_HOME%/webapps/axis2/WEB-INF/conf/axis2.xml
   2. Add the following TransportReceiver in the appropriate section of the document

      <transportReceiver name="https" class="org.apache.axis2.transport.http.AxisServlet"></transportReceiver>

   3. To restrict access to a service to only the HTTPS transport, add this to the services.xml for that service

<transports>
  <transport>https</transport>
</transports>

Configuring Tomcat

1. Open %TOMCAT_HOME%/conf/server.xml
2. Add the following Connector.  (Note: There probably is a Connector node for SSL traffic that’s commented out and can just be replaced.  This is for Tomcat 6 but I think Tomcat 5.x should be pretty similar.)

<Connector port="8443" protocol="HTTP/1.1"
  SSLEnabled="true" maxThreads="150" scheme="https"
  secure="true" clientAuth="true" sslProtocol="TLS" keystoreFile="conf/certs/localDevKeystore.bin"
  keyAlias="tomcatSSL" keystorePass="password"/>

Restart Tomcat.  You’ll need to use localhost (or whatever you entered as the name when creating the certificates) not your IP to connect.  Any service which either specifies the transport https in service.xml or doesn’t specify any transports should be accessible via https on port 8443 now.

Testing with SoapUI

Set up a SoapUI project to exercise the desired web service just like you normally would.  That’s not the scope of this document, but here’s a quick sample list (using default URIs.  If you’ve changed them, you shouldn’t need this list):

1. Navigate to the WSDL document for the service being tested.  Typically, that’s the endpoint for the service with ?wsdl appended.  Otherwise, you can go to http://localhost:8080/axis2/services/listServices and click on the name of the service.  That’ll open the WSDL.
2. Launch SoapUI (I actually use the IDEA or Eclipse plugin mostly, now)
3. Create a new WSDL Project, and specify the URI for the WSDL found in step 1.
4. If the endpoint for the service is different than the endpoint specified in the WSDL, change it.
5. Tweak the sample message as needed for the test.

If you submit the request, you should get a connection refused message.  You need to get SoapUI to use your certificates during the request.  Here’s how:

1. Open the SoapUI preferences and navigate to the SSL tab.
2. Enter the path to your generated keystore.  I recommend using %TOMCAT_HOME%/conf/certs/localDevKeystore.bin so everything is shared.
3. Enter password for the password.
4. Click OK.

Submit the request again.  Now, SoapUI should be using the client cert in the request, and SSL should be doing the verification magic it does.  You should get back whatever a proper response would be for your service.

SoapUI has an SSL Info tab as part of the response.  You can review that to verify the certs used were the ones expected.