Apache Tomcat or Tomcat server is powerful, open-source Java Servlet Container that implements multiple Java EE specs including JavaServer Pages (JSP), Java Servlet, WebSocket, and Java EL. The application powers large-scale, mission-critical systems in a wide range of well-respected organizations and industries. If your organization is using Tomcat server chances are, you are handling sensitive data. One of the best ways to provide optimal security to the data you process is installing SSL/HTTPS.

Apache Tomcat supports the Secure Socket Layer (SSL) protocol which is good news, but the bad news is that the configuration process can be a little overwhelming for newbies. Our comprehensive guide is assembled to help you configure HTTPS in Tomcat server in no time.

Ready? Letâ€™s get started!

Prerequisite:

Tomcat
Java SDK

Step 1: Create a Keystore

The first step when configuring HTTPS on Apache Tomcat is creating and editing a file known as the keystore. This is a very important file where will store all the keys used for SSL configuration. The file can be created using two ways:

Creating a new key or,
Sending an existing key to your keystore

For the sake of this guide, weâ€™ll focus on generating a new key using an application called the keytool. Depending on the computer you are using open the terminal using the command:

For Windows: cd %JAVA_HOME/bin
For Mac OS or Linux: cd $JAVA_HOME/bin

Run the command below:

"%JAVA_HOME%binkeytool" -genkey -alias tomcat -keyalg RSA
  -keystore pathtomykeystore

Make sure to substitute the appropriate syntax for your operating system (OS) and use your ideal Keystore path> and Alias.

Next, you will be requested to provide a password for your keystore. Select a strong password and keep it secure (donâ€™t forget the password). Provide the correct answer to all the questions:

Note: I have used strongpass as my password.

The keytool will create a file (.keystore) on the user home directory. The following will be the location of the file:

Windows: C: Docs and settings [username]
Mac: /users/ [username]
Linux : /home/ [username]

Step 2: Create the CSR

Once you have created the keystore, the next step is generating the CSR. The CSR is what your Certificate Authority (CA) will use to create the SSL certificate. You can leverage the power of the Java Keytool to generate the CSR, as well. Run the following command:

$JAVA_HOME/bin/keytool -certreq -keylag RSA -alias -file.csr -keystroke [path/to/your/keystore]

A file yourcertificatename.csr will be created. The file should be submitted to your Certificate Authority; the CA will use the file to create your unique certificate which can u be downloaded using the given instructions.

Step 3: Install the SSL certificate

SSL automatically authenticates the validity of a websiteâ€™s certificate using â€œtrust chainâ€. It initiates an extra handshake via your CA as specified in the siteâ€™s certificate.

Next, download your Root Certificate; from the Certificate Authority. This certificate helps you anchor the certificateâ€™s trust chain. Import the certificate together with the new siteâ€™s certificate into the keystore. Your Certificate Authority avails instructions to download your Root Certificate.

To import your Root Certificate use the following command:

keytool -import -alias root -keystore [path/to/your/keystore] -trustcacerts -file [path/to/the/root_certificate

Next import the new certificate using the command below:

$keytool-import -alias [youralias] -keystore [path/to/your/keystore] -file [path/to/your_keystore]

Once that is done, you can rest assured that your keystore is fully functional and certified. You can now proceed to the next step.

Step 4: Configure Apache Tomcat to utilize the Secure Socket Layer

The first thing when directing Tomcat server to utilize SSL is configuring its SSL connectors.

In the text editor open:

<tomcat-installation-directory>/conf/server.xml

The connector of interest is the one on port number 8443. To locate the connector, you should search for the following line: <! â€“ â€“ Define a SSL HTTP/1.1 Connector on port 8443 in:

The comment that encloses the connector provides a choice between the JSSE and Apache Portable Runtime (APR) configurations. It refers to SSL implementation we intend to use, JSSE (Apache Tomcatâ€™s Default Configuration).

Do you know what APR is? If no, replace the entry with the command below, to enable Tomcat server to find the keystore:

<connector port="8443" maxthreads="150" scheme="https" secure="true"
SSLEnabled="true" keystoreFile="path/to/your/keystore"
keystorePass="yourKeystorePassword" ClientAuth="false" keyAlias="yourAlias"
sslProtocol="TLS"/>

On the other hand, if you are experienced and know how APR works this option will work for you. The APR also was known as Tomcatâ€™s native library is the best practice especially if you are using Tomcat as a standalone server.

Modify the entry as follows to enable Apache Tomcat to utilize the APR OpenSSL instead of JSSE:

<connetcor port="8443" scheme="https" secure="true" SSLEnabled="true"
SSL CertificateFile+'/path/to/your/certificate.crt"
SSLCertificateKeyFile="/path/to/your/keyfile"
SSLPassword="YourKeystorePassword"
SSLCertificateChaineFile="path/to/your/root/certificate" KeyaAlias="yourAlias"
SSLProtocoal="TLSv1"/>

When using APR, the â€œSSLCertificateKeyâ€ and â€œSSLCertificateFileâ€ attributes should replace the KeystoreFile attribute.

Next, restart the Tomcat and open https://localhost:8443 in your browser to confirm HTTPS/SSL setup. The page should open over the secure HTTPS protocol.

Step 6: Limit SSL usage

The final step is limiting SSL usage. When you enable SSL/HTTPS in Apache Tomcat server.xml file it configures all files to run as both safe and insecure pages. This can cause unwanted server load, which can affect the performance of your system. For this reason, itâ€™s wise to select the application that should offer secure SSL connections. Add the following element <security-constraint> to the WEB-INF/web.xml file:

<security-constraint>
<web-resource-collection>
<web-resource-name> yourAppsName</web-resource-name>
<url-pattern>/#<Url-pattern>
</web-resource-collection>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>

This sets all SSL options for all your pages in a centralized place. To disable the SSL for all the pages, replace the â€œCONFIDENTIALâ€ with â€œNONEâ€.

Another important thing is specifying the implementation you want to use if you have installed connectors for JSSE and APR. Tomcat utilizes APR by default, but you can make it use JSSE by adjusting an attribute of the connectorâ€™s protocol as follows;

<connector protocol="org.apache.coyote.http11.HTTP11NioProtocol">

To force it to use APR, use the following command:

<connectore protocol="org.a[ache.coyote.http11AprProtocol">

Conclusion

During your operation (SSL configuration) you may encounter some errors if the settings such as aliases and keystore passwords are not entered correctly. Some of these settingâ€™s values are case-sensitive and should be used as set.