How to Install an SSL Certificate on Tomcat

Web server administrators, system administrators, and web developers may all play a role in installing an SSL Certificate on a Tomcat web server. These instructions will attempt to provide guidance for those.

I. Create a CSR with OpenSSL

To create a CSR with openssl, run the following command:

openssl req -newkey rsa:4096 -keyout key.pem -out req.pem -nodes

This is a basic example that you can use in most cases for creating your CSR. For more details on a CSR (Certificate Signing Request) and other ways to generate it, visit our post titled Certificate Signing Request. This post will go into more details on what a CSR is and more advanced options when using OpenSSL to create it.

Note that you MUST save your private key as it will be used when installing your SSL certificate in a later step. The CSR can be thrown away after submitting it to the CA you choose. If you would like, you may keep and reuse the CSR when renewing your certificate later, but we recommend always generating a new one.

After creating your CSR, you will then submit it to the CA (Certificate Authority) you will be buying your certificate from. The SSL Store is the company we recommend buying your certificate from and gives you a multitude of CAs and certificates to choose from. After submitting your CSR to them, they should issue your certificate quickly. Then you will be ready to proceed with installing your certificate in Tomcat.

II. Install the issued certificate in Tomcat

Previous Tomcat versions required the server certificate, intermediate certificate(s), and the private key to be installed in a keystore. The tomcat configuration would then read the keystore contents and secure your web server with its contents.

The instructions are based on Tomcat 10 configuration, which require the certificate, chain, and key to all be in separate files in the conf directory. Tomcat supports a pem certificate instead of the previously required pkcs12 keystore.

Place intermediates in a file, named chain.pem
Place your server certificate in a file named cert.pem.
Place your private key in a file named key.pem.
Configure the Tomcat SSL Connector with the keystore to enable SSL. The configuration should look like the following:

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
               maxThreads="150" SSLEnabled="true">
        <UpgradeProtocol className="org.apache.coyote.http2.Http2Protocol" />
        <SSLHostConfig>
                <Certificate certificateFile="conf/cert.pem" certificateKeyFile="conf/key.pem" certificateChainFile="conf/chain.pem" 
                         type="RSA" />
        </SSLHostConfig>
    </Connector>

Please note that this configuration is simply for a test environment and should be tweaked to suit your production requirements.

To highlight the different element attributes for the SSL certificate configuration:

certificateFile – The path to your end entity server certificate for your domain
certificateKeyFile – The path to the private key matching your SSL certificate
certificateChainFile – The path to the intermediate chain file.

III. Restart Tomcat and SSL should be configured to work.

service tomcat restart

After the restart, your site should now be protected and identified by the SSL certificate you installed.

IV. Verification and Troubleshooting Tomcat SSL

To verify your SSL configuration on your Tomcat web server you can do a couple of things.

Visit your website from a browser and check the installed SSL certificate, as well as whether or not the website is served from https. If there is an SSL error or misconfiguration, your browser will deliver that error to you.
Check your SSL configuration with our SSL Tools. Our tools include an SSL Certificate Decoder as well as an SSL checker to troubleshoot your SSL details.

Most configuration problems come down to the certificate chain not being installed correctly. Again, make sure to include the end entity server certificate, the certificate chain (intermediate certificates), and private key all in the same keystore at the same alias.

Tomcat SSL configuration with docker

To provide a simple example of configuring SSL and SSL certificates with Tomcat, let’s spin up a quick docker instance to demonstrate how to do so. This is meant simply for an educational exercise and is by no means a complete production ready example, but will cover the basics to get you started. Docker Tomcat SSL could not be easier.

Create a new directory

mkdir tomcat-docker; cd tomcat-docker

Create a new file named server.xml. This file may be copied from the tomcat instance installed in your docker container.
Create a directory named ssl and move your cert.pem and key.pem files into it. Note that cert.pem should be formatted as described earlier in this article. If your SSL certificate and private key files are named differently, then make sure to update the server.xml file accordingly.
Create the docker-compose.yml file. Its contents should be as follows:

version: '3.8'
services:
        tomcat:
                image: tomcat
                ports:
                        - "8080:8080"
                        - "8443:8443"
                volumes:
                        - /home/misterpki/tomcat-docker/conf:/usr/local/tomcat/conf

Run docker-compose to spin up the Tomcat instance with your SSL certificate installed and configured.

docker-compose up --build

After running your tomcat instance, the logs should show SSL working.

Note that in this example, a self-signed certificate is being used that has a CN different than localhost, so you will see browser warnings. For one, the certificate is not trusted by the OS (Operating System) certificate store. Secondly, the CN does not match the host name. When using a publicly trusted certificate issued to your domain, you should not see any SSL Certificate errors.

For the full example, visit our GitHub repo containing the files to run the docker example of Tomcat and SSL certificates.

Conclusion

We hope to have covered the Tomcat SSL setup in full on how to successfully install an SSL certificate on a Tomcat web server. If you have any questions suggestions on how to improve this article please leave us a comment. If you need assistance on troubleshooting your SSL installation or need help finishing, send us an email at info@misterpki.com.