Security → HTTPS for Apache Tomcat with OpenSSL

About HTTPS for Apache Tomcat with OpenSSL

The Incorta Cluster Management Console, Loader Service, and Analytics Service are Java web applications that run on Apache Tomcat, a web application server. One way to secure communications between a web browser and an Incorta Cluster is to configure Hypertext Transfer Protocol Secure (HTTPS) support for Apache Tomcat.

As a protocol, HTTPS requires encrypted communications between websites, web applications, and web browsers. HTTPS requires Transport Layer Security (TLS). TLS requires a valid TLS certificate. In the web browser, you must explicitly declare https for the Universal Resource Locator (URL) of a website or web application with a valid TLS/SSL certificate. Often, security administrators reference the predecessor terminology of a Secure Socket Layer (SSL) certificate. For this reason, this document will refer to a TLS certificate as a TLS/SSL certificate.

Typically, a security or system administrator for the operating system with root access configures HTTPS for Apache Tomcat for the Incorta Cluster. This includes opening the host network port for HTTPS which is 8443 by default for the Incorta Analytics Service.

You may want to also consider alternative options for HTTPS to secure communications through a reverse proxy server such as NGINX or Apache.

About OpenSSL

OpenSSL is a robust, commercial-grade, and full-featured toolkit for the TLS and SSL protocols. OpenSSL is licensed under an Apache-style license and is available for free for both commercial and non-commercial purposes subject to license conditions.

Warning

Please be aware that the import, export, and/or use of strong cryptography software, providing cryptography hooks, or even just communicating technical details about cryptography software is illegal in some parts of the world.

About security certificates

Although you can use a self-signed certificate for an internal or developer environment, production systems require a certificate from a Certificate Authority (CA).

Important

Incorta does not recommend using a self-signed certificate as this can restrict access to critical data source connectors such as Google Drive and Google Sheets.

Before issuing a certificate to an applicant, a CA validates a domain’s ownership. Your web browser contains a list of CAs trusted by the browser vendor to perform the validation. A TLS certificate consists primarily of a public key that corresponds to your private server key, and a signature by the CA that is cryptographically tied to the public key.

In other words, when using a HTTPS URL (https://www.mycompany.com), your web browser connects to a web server and the web server presents a certificate for your web browser to check. Your web browser submits the certificate to a list of trusted CAs. If the signer is on the list, or is accessible through a chain of trust consisting of other trusted signers, the browser negotiates an encrypted data channel with the web server.

Keystore formats and supported implementations for Apache Tomcat

This release of Incorta runs on Apache Tomcat 9.0. Apache Tomcat 9.0 supports JKS, PKCS11 or PKCS12 keystore formats. The JKS format is the standard Java KeyStore format. The PKCS12 format is an open source standard for the internet. You can use OpenSSL or Microsoft’s Key-Manager to work with the PKCS12 format.

Apache Tomcat 9.0 supports two ways to implement TLS/SSL:

Java Secure Socket Extension (JSSE)
Apache Portable Runtime (APR) implementation which uses the OpenSSL engine by default

You define the TLS/SSL implementation in a Connector element of the server.xml file for Apache Tomcat.

For the most part, a Connector for JSSE requires the JKS format and a Connector for APR requires a PCKCS12 keystore format. The PCKCS12 keystore format supports OpenSSL.

Create a free TLS/SSL certificate for HTTPS with LetsEncrypt, Certbot, and OpenSSL

The Electronic Frontier Foundation (EFF) sponsors Let’s Encrypt as a Certificate Authority (CA) with the goal of encrypting the entire internet. Let’s Encrypt has issued over 1 billion security certificates, 225 million of which are for public websites. Originally a Let’s Encrypt project, and now formally sponsored by EFF, Certbot is a service that provides free HTTPS certificates, including renewals. Certbot creates a certificate to use with OpenSSL.

Note

In order for Certbot to create a TLS/SSL certificate, you must first update the Domain Name Service (DNS) A/AAAA record(s) for a top-level domain to reference the Public IPv4 of a website. In most cases, enterprises and organizations host an Incorta Cluster behind a firewall, within a Virtual Private Network (VPN). Most Security Administrators already have an existing TLS/SSL certificate available for use within their enterprise subdomains behind firewalls. With that in mind, consider this document as an example of the related steps for HTTPS configuration.

In order to create a TLS/SSL certificate with Certbot and configure HTTPS for the Incorta Node that runs the Analytics Service, you must have root access to the host.

Implement HTTPS for Apache Tomcat with OpenSSL and Certbot

Important

Implementing HTTPS for the host with the Incorta Node running the Analytics Service requires that you stop and start the Analytics Service.

Here are the prerequisites for implementing HTTPS for Tomcat using OpenSSL and Certbot for the host with the Incorta Node that runs the Analytics Service:

Update the Domain Name Server A/AAAA record(s) for a top level public domain to reference the Public IPv4 of the host.
Open port 8443 as this is the default port for HTTPS for the Analytics Service.
Confirm root access to the host.
Install OpenSSL on the host.

In order to stop the Analytics Service, you must also have access to the Cluster Management Console (CMC) for the Incorta Cluster.

Install OpenSSL

Here are the steps to install OpenSSL:

SSH into the host with the Incorta Node that runs the Analytics Service.
As the root user, install OpenSSL with yum:

sudo su
yum install openssl-devel

Install Certbot

Here are the steps to install Certbot:

As the root user, onstall Certbot with yum:

yum install certbot

With Certbot, create a certificate

Here are the steps to create a standalone certificate for your domain:

As the root user, create a standalone certificate for the domain with Certbot, replacing <My_Domain>:

MY_DOMAIN=<My_Domain>
certbot certonly --standalone -d $MY_DOMAIN

Verify the creation of cert.pem, chain.pem, fullchain.pem, and privkey.pem:

ls -l /etc/letsencrypt/live/$MY_DOMAIN

Create a PKCS12 keystore archive file

A .pfx file is a PKCS12 archive file. The PFX format is a single encrypted file in binary format that contains the server certificate, any intermediate certificates, and the private key. Here are the steps to create the .pfx file with OpenSSL:

As the root user, navigate to domain cert directory and create the file with OpenSSL, replacing <File_Name> and <Password>.

MY_PFX_FILE=<File_Name>
MY_PFX_PASSWORD=<Password>
cd /etc/letsencrypt/live/$MY_DOMAIN
openssl pkcs12 -export -out ${MY_PFX_FILE}.pfx -inkey privkey.pem -in cert.pem -certfile chain.pem -password pass:${MY_PFX_PASSWORD}

Verify the creation of the .pfx file.

ls -l /etc/letsencrypt/live/$MY_DOMAIN | grep $MY_PFX_FILE

Warning

Never share the privkey.pem. After Certbot creates this file and you create the .pfx file, take the necessary steps to safeguard the privkey.pem file accordingly to your organization's cybersecurity practices.

Move the PKCS12 keystore archive file to the Incorta installation parent directory

Here are the steps to move the .pfx file:

Create a certs directory in the parent directory of the Incorta Analytics installation path, replacing <Incorta_Analytics_Install_Path>. This should be similar to /home/incorta/IncortaAnalytics.

INCORTA_ANALYTICS_INSTALL_PATH=<Incorta_Analytics_Install_Path>
cd $INCORTA_ANALYTICS_INSTALL_PATH
mkdir ../certs/

Move the .pfx file.

mv /etc/letsencrypt/live/${MY_DOMAIN}/${MY_PFX_FILE}.pfx ../certs/${MY_PFX_FILE}.pfx

Verify that the .pfx file exists in the new directory.

ls -l ../certs/ | grep $MY_PFX_FILE

Modify the file bits and ownership of the file

Most likely the Incorta Analytics process runs as the incorta Linux user. For this reason, you will need to change the ownership of the certs directory to match that of the user that runs the Incorta process for the Analytics Service. You will also need to modify the file bits so that the Incorta user can read the file. Follow these steps:

Change the ownership of the certs directory to the incorta Linux user.

cd ..
sudo chown -R incorta:incorta certs/
sudo chmod 0640 certs/${MY_PFX_FILE}.pfx

View the path to the certs directory as you will need this reference later.

pwd

Leave this SSH bash terminal open as you will continue on and configure HTTPS for Apache Tomcat.

Stop the Analytics Service from the CMC

Sign in to the CMC with the administrator username and password.
In the Navigation bar, select Clusters.
In the List view, select the specific cluster.
In the canvas tabs, select Services.
In the Services list view, select the name of the service of the type Analytics.
In the details page, in Runtime footer, select Stop.
Keep the CMC open as you will shortly Start the Analytics Service again.

Enable HTTPS over port 8443 on the Analytics service

Here are the steps to configure HTTPS for Apache Tomcat on the host with the Incorta Node that runs the Analytics Service:

As the incorta user or another user that runs the Incorta Analytics Service process, identify the Globally Unique Identifier (GUID) for the Analytics Service, replacing <Incorta_Analytics_Install_Path>. This should be similar to /home/incorta/IncortaAnalytics.

sudo su incorta
INCORTA_ANALYTICS_INSTALL_PATH=<Incorta_Analytics_Install_Path>
cat $INCORTA_ANALYTICS_INSTALL_PATH/IncortaNode/services/services.index

Change directories to the Analytics Service, replacing <Analytics_Service_GUID> with the GUID from the previous cat command output.

cd $INCORTA_ANALYTICS_INSTALL_PATH/IncortaNode/services/<Analytics_Service_GUID>/conf/

Create a backup file of the server.xml file.

cp server.xml server.xml.bak

In vim, edit the server.xml (i keystroke to edit in INSERT mode, ESC for read-only), replacing <Incorta_Analytics_Certs_Directory_Path>,<File_Name>, and <Password> for the keystoreFile and keystorePass attributes:

<Connector port="8443" protocol="HTTP/1.1"
 maxThreads="500" SSLEnabled="true" scheme="https" secure="true"
 URIEncoding="UTF-8"
 clientAuth="false"
 sslProtocol="TLS"
 keystoreType="PKCS12"
 keystoreFile="<Incorta_Analytics_Certs_Directory_Path>/<File_Name>.pfx" keystorePass="<Password>"
 compression="on"
 compressionMinSize="100"
 noCompressionUserAgents="gozilla, traviata"
 compressableMimeType="text/html,text/xml,text/plain,text/css,application/javascript ,application/json"
 maxHttpHeaderSize="10485760" maxPostSize="10485760" />

To save your changes to server.xml, use the keystroke :wq! (force-quit-save).

Start the Analytics Service from the CMC

If needed, sign in to the CMC with the administrator username and password.
In the Navigation bar, select Clusters.
In the List view, select the specific cluster.
In the canvas tabs, select Services.
In the Services list view, select the name of the service of the type Analytics.
In the details page, in Runtime footer, select Start.

Verify the HTTPS configuration

Now that HTTPS is configured for Apache Tomcat using OpenSSL, you can verify the configuration. The default port for HTTPS for the host with an Incorta Node running the Analytics Service is 8443. Here are the steps to confirm HTTPS:

In a supported web browser, in the Address bar, enter https:<My_Domain>:8443/incorta, replacing <My_Domain> as required.
Verify that you see the Sign-In form.

Content