Adding SSL (HTTPS) security with Tomcat/Java solution in Windows Azure

Once you have your Tomcat/Java based solution running on port 80 in Windows Azure you may decide to add HTTP endpoint to it or by the start of your service development you want to support HTTP and HTTPS endpoint with your Tomcat/Java service. To add a HTTPS endpoint to regular .net based service is very easy and described everywhere however adding a HTTPS endpoint to Tomcat/Java based service is little different. The reason is that for managed service the SSL certificate is managed by managed modules you get the SSL certificate from the system however in Tomcat manages SSL certificate its own way that’s why it is slightly different. This document helps you to get the HTTPS endpoint working with your Tomcat/Java service on Windows Azure.

Adding HTTPS security to any website is basically a certificate based security based on PKI security concept and to start with you first need to obtain a valid certificate for “client and server validation” from a Certificate Authority i.e. “Verisign” or “Go Daddy” or “Thawte” etc. I will not be discussing here who you will choose and how you will get this certificate. I would assume that you know the concepts and have certificate ready to add HTTPS security to your Tomcat service.

You will be given a Certificate to verify your domain name such as www.yourdomain.com so the certificate will be linked to your domain this way.

The process of adding SSL to tomcat is defined in the following steps:

1. Getting certificates from CA and then creating keystore.bin file

2. Adding keystore.bin file to tomcat

3. Adding HTTPS endpoint to your tomcat solution

4. Adding certificate to your Tomcat service at Windows Azure Portal

Here is the description of each above steps:

Getting certificates from CA and then creating keystore.bin file

To get these certificates you will need to create a CSR request from your tomcat/apache server so you can create a folder name keystore and create and save the CSR request contents there.

C:\Tomcat-Azure\TomcatSetup_x64\Tomcat\keystore

Most of the time you will get a certificate chain which includes your certificate, intermediate certificate and root certificate so essentially you will have 3 certificates:

1. RootCertFileName.crt

2. IntermediateCertFileName.crt

3. PrimaryCertFileName.crt

Now once you received the certificate please save all 3 certificates in the keystore folder.

C:\Tomcat-Azure\TomcatSetup_x64\Tomcat\keystore

The certificate will only work with the same keystore that you initially created the CSR with. The certificates must be installed to your keystore in the correct order.

We will be using Keytool.exe a JAVA tool to link these certificates with Tomcat. To tool is located at:

C:\Tomcat-Azure\Java\jre6\bin\keytool.exe

Every time you install a certificate to the keystore you must enter the keystore password that you chose when you generated it so you will keep using the same password.

Now open a command window and use the keytool binary to run the following commands.

Installing Root Certificate in keystore:

keytool -import -trustcacerts -alias root -file RootCertFileName.crt -keystore keystore.key

There are two possibilities:

1. You may receive a successful message as then we are good.

"Certificate was added to keystore".

2. You may also receive a message that says

"Certificate already exists in system-wide CA keystore under alias <...> Do you still want to add it to your own keystore? [no]:

This is because the certificate may already stored in keystroke so select “Yes”

You will see the message”

"Certificate was added to keystore".

             Now we have added our Root certificate in the keystore.

Installing Intermediate Certificate in keystore:

keytool -import -trustcacerts -alias intermediate -file IntermediateCertFileName.crt -keystore keystore.key

You will see a message as:

"Certificate was added to keystore".

             We are good now.

Note if you don’t have an intermediate certificate not a problem and you can skip this step.

Installing Primary Certificate in keystore:

keytool -import -trustcacerts -alias tomcat -file PrimaryCertFileName.crt -keystore keystore.key

You will see a message as:

"Certificate was added to keystore".

             We are good now.

After it we can be sure that we have all certificates installed in keystore file.

Note you can actually see the contents of keystore.bin

Adding keystore.bin file to tomcat:

Our next step is to configure your server to use the keystore file.

Please get keystore.bin & yourdomain.key from the CSR creation location and then copy to your tomcat webapps folder:

Now open server.xml file from Tomcat\conf\server.conf and edit as below:

Note:

1. Please be sure to have the same password as you had after CSR creation and used with keytool application.

2. There are other methods to add keystore to tomcat so please look around on internet if you decided to prefer other methods.

Verify that you have SSL working in Development Fabric.

https://127.0.0.1:81

Adding HTTPS endpoint to your tomcat solution

Our next step is to add HTTP endpoint to Tomcat solution. Please open the tomcat solution in visual studio which is located at:

C:\Tomcat-Azure\TomcatSetup_x64\Tomcat\Tomcat.sln

Once the solution is open please select the TomcatWorkerRole and open its properties dialog box as below:

Now please select “Endpoints” tab and you will see the windows as below:

In the “Endpoints” tab please select “Add Endpoint” button and add TCP endpoint with port 443.

For Tomcat the HTTPS endpoint defined as a “tcp” endpoint like HTTP. Setting protocol to “http” or “https” means that Azure will perform an http.sys reservation for that endpoint on the appropriate port. Since Tomcat does not use http.sys internally, we needed to make sure to model tomcat HTTPS endpoints as “tcp”.

You will also see that setting up tomcatSSL endpoint to TCP with port 443 then the SSL Certificate field get disabled so regular certificate cannot be used as below:

Now to make things in full perspective, we already know that Tomcat already has SSL certificates in its keystore.bin, so using TCP endpoint with port 443 will work even there is no certificate associated with it.

Now please save the project and verify that ServiceDefinition.cdef have the following data:

Now if you build your package using Packme.cmd these new changes will be in effect.

Adding certificate to your Tomcat service at Windows Azure Portal

Our next step is to add certificates in the Azure portal.

You need to get the Windows Azure Portal and your Tomcat Service page where you have your production and staging slots and go the “Certificates – Manage” section as below:

Now please select Manage and you will see the following screen:

In the above web windows please select all 2/3 PFX certificates (Root, Intermediate and Primary) and enter the password correctly if associated.

Once upload is done you will see the all the certificates located on portal as below:

You can also see the list of certificates install on server as below:

Now when you publish your service to Azure portal these certificates will be used to configure your Tomcat service and you will be able to use SSL with your Tomcat service.