Spotfire Server: Configuring HTTPS connections to the Spotfire Server

The following article explains how to implement TLS connections within Spotfire server.

A familiarity of how SSL certificates work is assumed. If you are new to this topic a good introduction can be found here.

The Spotfire server by default will only allow connections to it via HTTP. The following procedure explains how to enable secure communications to the Spotfire Server via HTTPS.

There are two main methods for creating certificates for use in TLS connections in Spotfire, using a PFX file or Java keystores, however the use of PFX files is recommended.

Using your own PFX certificates (preferred method)

If your organisation has already produced an SSL certificate to be used in Spotfire, the following method can be used to be implement these.

This is the preferred method of configuring https, since it is simpler and easier to maintain.

This method assumes that a PFX (P12) or PEM file / private key are already available and has been produced outside of Spotfire. The certificate must meet these requirements:

1) The certificate issued must have a Common Name (CN) for the primary URL of the spotfire server.

2) The primary hostname must also be listed as a Subject Alternative Name (SAN), along with any other SAN's that are relevant. Please refer the linked article as the beginning of this document for an explanation of SANs.

3) With PFX (P12) files the certificate must include any intermediary certificates in the chain, in the correct order. This is 
     Leaf certificate -> Intermediary 1 -> Intermediary 2 (if needed)

The Spotfire server can make use of PFX (P12) format certificates directly. If your certificate vendor has provided a PEM format file (.crt / .pem / .cer) and a key, these need to be converted to PFX prior to configuring the Spotfire connnector.

1. Converting the certificates to PFX (PKCS12)

If only a PEM format certificate and private key pair are available then these must be merged into a PKCS12 certificate first, otherwise skip to step 2.

You must also have the intermediary certificate available. The certificates can be merged to PFX using as follows:

 On Linux use openssl as follows (e.g.)

On Windows certutil can accomplish the same task.

Firstly, combine the leaf certificate (spotfire server certificate) and the intermediary certificate. Then rename the private key to the same base filename.

The certifcate and key can merged to PFX like this:

2.  Edit the server.xml 

These lines from the server.xml should be removed.

The SSLHostConfig section of the <INSTALLATION ROOT>\tomcat\conf\server.xmlfile must be edited as follows:

  <SSLHostConfig certificateVerification="none"
                 sslProtocol="TLS"
                 protocols="+TLSv1.2,+TLSv1.1,+TLSv1"
                 honorCipherOrder="true"
                 ciphers="TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, (long list of ciphers) SSL_RSA_WITH_3DES_EDE_CBC_SHA">
          <Certificate certificateKeystoreFile="./certs/spotfire.pfx"
                certificateKeystorePassword="changeit"
                certificateKeystoreType="pkcs12"/>
      </SSLHostConfig>

Important note:
If the private key in the PKCS12 certificate contains a password, then the PKCS12 certificate password must match that one. Please consult your certificate vendor to ascertain this before continuing.

This completes the configuration of the TLS connector. After restarting the Spotfire service connections should work via https.

Creating a new certificate via the keytool command

Java Keystores

Java utilises a keystore for SSL certificate / private key storage. This is a binary file which is a repository of SSL certificates for use with connectors in Tomcat. Keystores can be managed by using the Java keytool utility, which is located in:

<INSTALLATION ROOT>/jdk/bin/keytool

Each certificate in the keystore has an alias associated with it, which is just a label for that certificate.

If your organisation cannot produce certificates, a new certificate can be requested and imported via the Java keytool command.

This is a propriety format to Java, and PKCS12 certificates should be used wherever possible to simplify implementation and administration.

In this example, we have a primary spotfire URL of https://spotfire.example.com with an alternate name of https://myspotfire.example.com. Users may also access the Spotfire server via its IP address.

All possible methods of accessing the spotfire server need to be specified as SANs, otherwise this will lead to trust warnings in the browser.

1. Generate a new private key. Include the SAN parameter to specify SAN's. This must at least contain the primary hostname (same as the common name) as one SAN. In this example we also specify an IP SAN so the server can be accessed via https://10.4.1.88

Note an alias parameter is also specified, this is simply a label to give to the private key.

2. Generate a new signing request (CSR) based on this keystore

This will generate a CSR file spotfire.csr. The CSR must be submitted to your chosen CA to obtain a new certificate. You must have a copy of the certificate in PEM format

3. Once you have received your certificate and related intermediate certificates, these must be combined to create a full chain. This is done via the type command in Windows (Linux users can do the same with cat)

4.  Import the PEM format certificate as follows:
Note that the the same alias name of "spotfire" is being used when importing the certificate.

If whilst executing this command you get the error:

This means that order of leaf (server) certificates and intermediate certificates are not correct. Check and repeat step 3.

5. Update the <INSTALLATION ROOT>/tomcat/conf/server.xml with the keystore information

Below is an example of what the SSLHostConfig section of the server.xml should look like:

Note that as in the previous section the lines with trustStore are deleted.

  <SSLHostConfig certificateVerification="none"
                 sslProtocol="TLS"
                 protocols="TLSv1.2+TLSv1.3"
                 honorCipherOrder="true"
                 ciphers="TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384,... long list of ciphers">
      <Certificate certificateKeystoreFile="./certs/spotfire.jks"
                   certificateKeystorePassword="changeit"
                   certificateKeystoreType="jks"
                   certificateKeyAlias="spotfire"/>
  </SSLHostConfig>
  

This completes the configuration of the TLS connector. After restarting the Spotfire service connections should work via https.

Enforcing TLS connections

It’s possible to make use of Tomcats rewrite engine to force clients to use https. This is done by rewriting traffic destined to port 80 to port 443 instead. Note that both ports 80 and 443 must be able to accept incoming connections on the server, so do not block access to port 80.

1.)  In the file server.xml add the following line after the ‘<Context‘ section

This adds a new Valve which enables Tomcats rewrite engine.

2.) Create the following file

3.) The content of this file is as follows (alter the hostname as appropriate)

Restart the Spotfire server to make this effective.

Trusted Root CA certificates

Java has a global truststore file called  cacerts which is located in <INSTALLATION ROOT>/jdk/lib/security/cacerts.  This truststore contains trusted root CA certificates and it is used in the following circumstances.

- When Spotfire needs to make an outbound connection to a 3rd party TLS enabled connection. (e.g. LDAPS, a database using TLS etc)

- For inbound connections where mTLS is used (i.e client certificates). 

The former scenario is far more common, and occasionally it's required to import certificates into cacerts to allow connectivity to 3rd party machines

This can be done via the keytool command as follows (e.g.): Repeat for each certificate that needs to be imported. E.g.

The default password for this is changeit

Using the Windows Certificate Store

It may be desirable to use the Windows Certificate Store to implement SSL connections in Spotfire. Please refer to the following article for details on how to do this.

Useful commands

1.) Converting a Java keystore to PKCS12 format.

2.) Convert a DER format certificate to PEM

3.) If the java keystore does not have the correct alias name as specified in the server.xml as error such as

may be seen.

This means that the alias contained inside the keystore does not match the one specified inside the server.xml. Either correct the server.xml, or the alias may be renamed as follows:

Check the current alias name. In this case the alias is "mycert"

Rename to the correct alias name, e.g. spotfire (matching the alias name in the server.xl)