How to use a PKI certificate with Tomcat

on September 8, 2015

In this blog post I am going to set-up secure access to a web application running on Tomcat (on Windows 2012 R2) by using a certificate from an internal PKI.

I am going to use KeyStore Explorer 1.1 (mirror) for the creation and modification of the KeyStore. This GUI tool makes it easier than the command line.

Use the PastBin URL to copy and paste the code in the correct format.

Install KeyStore Explorer 1.1 Note: Since KeyStore explorer needs Java, the easiest is to install it on the Tomcat server.
Start KeyStore Explorer
In KeyStore Explorer, click on Create a new KeyStore
Select JKS and click Ok
Click on Generate Key Pair
Leave the default values and click Ok

Change the period that the certificate is valid and click on the Book icon
Enter the correct information for your environment. Make sure the CN name is the same name that end-users are going to use to access the application. Click Ok
The name field is now filled, click Ok
Enter an alias for the Key Pair
Enter a password for the Key Pair. Save the password for later use!

Right click on the Key Pair and select Generate CSR
Change the location of the CSR file and click OK

Give the CSR file to your PKI administrator to generate a CER file.
When you have received the CER file, right click on the Key Pair and select Import CA Reply Select the CER file and click Ok

Next, import both the root certificate and the intermediate certificate of your PKI. Click on Import Trusted Certificate and select the root or intermediate certificate
Use the name inter for your Intermediate certificate
Use the name root for your root certificate
Successfully added the root and intermediate certificates.
Now the file looks like this: Note: The certificate from the PKI infrastructure is not separately added. It is only used to sign the private key.
Save the file (.jks) in a Tomcat directory, I prefer the Conf folder.
Open Server.xml from the Tomcat Conf directory and add: <Connector port=”443″ maxThreads=”150″ scheme=”https” secure=”true” SSLEnabled=”true” keystoreFile=”conf/contoso_keystore” keystorePass=”<password>” keyAlias=”mysite.contoso.com“ clientAuth=”false” sslProtocol=”TLS”/> Change the red values. First is the filename of your KeyStore in the Conf directory Second is your KeyStore password Third is the name of your KeyPair in the KeyStore.	PasteBin URL
Save the Server.xml file and restart Tomcat.
Go to https://yoursite/application to view the secure contents.

If you encounter any issues, please check the following:

1. You need to sign the private key in your Keystore with the certificate from your PKI.

Only adding the Certificate to your Keystore is not enough!

2. You need to point to the correct KeyStore file in Server.xml.

3. The keyAlias should point to the Private key and not to the root, intermediate or the PKI certificate (if added)

3. If you change the port number, make sure it is not in use by any other process on the system or by an other connector port in the Tomcat configuration (Server.xml).

4. Check the catalina log in the Logs directory of Tomcat for more information if there are any errors.

5. If you receive the error: Connector attribute SSLCertificateFile must be defined when using SSL with APR in Catalina.log, then comment out line 27 in Server.xml. That line states:

<Listener className=”org.apache.catalina.core.AprLifecycleListener” SSLEngine=”on” />

Result:

Redirect traffic from port 80 to 443

Now that the server is running on port 443, traffic coming in from port 80 should be redirected to port 443 to use HTTPS.

Open Server.xml from the Tomcat Conf directory and verify that the port 80 connector contains redirectPort=”443”.

PasteBin URL

Open Web.xml from the Conf folder and add:

<security-constraint>
<web-resource-collection>
<web-resource-name>Protected Context</web-resource-name>
<url-pattern>/*</url-pattern>
</web-resource-collection>
<user-data-constraint>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>