Skip to main content

Spotfire Server: Configuring HTTPS connections to the Spotfire Server

Sukesh Nischal
  • Created


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 several methods for creating certificates for use in TLS connections in Spotfire, as described below.

Creating a new self-signed certificate


It is possible to create self-signed certificate, however this process is not recommended for production environments, and should be restricted to test or development systems only.

Note that this method will give trust issues in the browser (invalid certificate errors) when connecting to the Spotfire server.

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.

To create a keystore with a self-signed certificate, use the keytool command as follows:

This example will create a Java keystore file keystore.jks. This has an alias of mycertand password of changeit.

 

1. Issue the following commmand to create the new keystore

keytool -genkey -alias spotfire -keyalg RSA -keypass changeit -storepass changeit
        -keystore keystore.jks


2. You will then be prompted with a series of questions about the certificate details. Note that the Common Name (first name, last name) must match the hostname of the spotfire server

What is your first and last name?
[Unknown]: spotfire.example.com
What is the name of your organizational unit?
[Unknown]: Operations
What is the name of your organization?
[Unknown]: Acme Corp
What is the name of your City or Locality?
[Unknown]: Austin
What is the name of your State or Province?
[Unknown]: Texas
What is the two-letter country code for this unit?
[Unknown]: US
Is CN=spotfire.example.com, OU=Operations, O=Skynet Corp, L=Austin, ST=Texas, C=US correct?
[no]: yes

Enter key password for <spotfire>
(RETURN if same as keystore password):

3. The keystore can be verified as follows:

# keytool -list -keystore keystore.jks
Enter keystore password:
Keystore type: JKS 
Keystore provider: SUN 
Your keystore contains 1 entry spotfire, 04-Sep-2015, PrivateKeyEntry,
Certificate fingerprint (SHA1): 29:18:8E:DA:B1:58:2C:D4:C0:56:90:A2:9F:B4:0A:72:FB:C6:9A:67

4. The keystore should then be copied to the directory:

<INSTALLATION ROOT>\tomcat\certs


5. Edit the <INSTALLATION ROOT>\tomcat\conf\server.xml

These lines from the server.xml should be removed.

truststoreFile="./certs/[server hostname].jks"
truststorePass="changeit"
truststoreType="jks"

The Connector section of this file should look as below:

<SSLHostConfig certificateVerification="none"
               sslProtocol="TLS"
               protocols="TLSv1.2+TLSv1.3"
               honorCipherOrder="true"
               ciphers="TLS_AES_128_GCM (long list of ciphers) TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256">
               <Certificate certificateKeystoreFile="./certs/keystore.jks"
                            certificateKeystorePassword="changeit"
                            certificateKeystoreType="jks"
                            certificateKeysAlias="spotfire"
               />
</SSLHostConfig>

 

4. Restart the Spotfire Server. You should then find connections to the Spotfire server work over https.


Using your own 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.

A CSR could be produced via the certreq in Windows or openssl in Windows.

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

Additionally this must 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

The Spotfire server can make use of PFX (PKCS12) format certificates directly. If your certificate vendor has provided a PEM format file (.crt / .pem / .cer) 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 is available then these must be merged into a PKCS12 certificate first. This can be accomplished via the command line.


 On Linux enter the following command (e.g.)

openssl pkcs12 -export -out spotfire.pfx -in spotfire.pem -inkey spotfire.key


On Windows certutil can accomplish the same task.
The private key must have a .key extension and have the same base file name.

E.g. A directory could contain a spotfire.cer and spotfire.key file. This command will produce a PFX file.

certutil –MergePFX spotfire.cer spotfire.pfx


2.  Edit the server.xml

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

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

<SSLHostConfig certificateVerification="none"
                   sslProtocol="TLS"
                   protocols="+TLSv1.2,+TLSv1.1,+TLSv1"
                   honorCipherOrder="true"
                   ciphers="TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
                   TLS_ECDHE_RSA_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 PKC12 certificate password must match that one.


3. Import the root CA and any intermediate certificates

Any root CA certificates or intermediate certificates should be imported into the global truststore cacerts which is located in <INSTALLATION ROOT>/jdk/jre/lib/security/cacerts. The default password for this is changeit

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

keytool -import -file CACert.pem -alias MyCACert -keystore <INSTALLATION ROOT>/jdk/jre/lib/security/cacerts -trustcacerts -storepass changeit


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


If your own certificates are not available, a new certificate can be produced 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.


This method is similar to the first section "Creating a new self signed certifcate" except the certificate will be signed by a CA.

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 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.

keytool -genkey -alias spotfire -keyalg RSA -keystore keystore.jks -keysize 2048 
        -storepass changeit -ext SAN=dns:spotfire.example.com,dns:myspotfire.example.com,ip:10.4.1.88
What is your first and last name?
  [Unknown]:  spotfire.example.com
What is the name of your organizational unit?
  [Unknown]:  Operations
What is the name of your organization?
  [Unknown]:  Acme Corp
What is the name of your City or Locality?
  [Unknown]:  Austin
What is the name of your State or Province?
  [Unknown]:  Texas
What is the two-letter country code for this unit?
  [Unknown]:  US
Is CN=spotfire.example.com, OU=Operations, O=Skynet Corp, L=Austin, ST=Texas, C=US correct?
  [no]:  yes
 
Enter key password for <spotfire>
        (RETURN if same as keystore password):

2. Generate a new CSR based on this keystore

keytool -certreq -alias spotfire -keystore keystore.jks -file spotfire.csr
-ext SAN=dns:spotfire.example.com,dns:spotfire1.example.com,ip:10.4.1.88

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 CA certificates, import any root CA's or intermediary certificates into the global truststore (see step 3 in the previous section : Import the root CA and any intermediate certificates)


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

 keytool -import -trustcacerts -alias spotfire -file spotfire.pem -keystore keystore.jks

If whilst executing this command you get the error:

keytool error: java.lang.Exception: Failed to establish chain from reply

This means that the CA or intermediate certificates are not correct or have not been imported correctly. 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:


<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>

Note that again the following lines should be deleted from the server.xml 

truststoreFile="./certs/server hostname.jks"
truststorePass="changeit"
truststoreType="jks"

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


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.


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.

<Valve className="org.apache.catalina.valves.rewrite.RewriteValve" />

2.) Create the following file

tomcat/conf/Spotfire/localhost/rewrite.config

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

RewriteCond %{SERVER_PORT} =80
RewriteRule ^/?(.*) https://spotfire.example.com/$1 [R=301,L]

Restart the Spotfire server to make this effective.


Useful commands

1.) Converting a Java keystore to PKCS12 format.

keytool -importkeystore -srckeystore [source keystore] -destkeystore [dest_keystore.pfx] -srcstoretype JKS - deststoretype PKCS12


2.) Convert a DER format certificate to PEM

openssl x509 -in cert.der -out cert.pem


3.) If the java keystore does not have the correct alias name as specified in the server.xml as error such as
Alias name[certificate_alias_name] does not identify a key entry.

may be seen.

In this situation the alias may be renamed as follows:

Check the current alias name:

# keytool -list -keystore keystore.jks
Enter keystore password:
Keystore type: JKS 
Keystore provider: SUN 
Your keystore contains 1 entry mycert, 04-Sep-2015, PrivateKeyEntry,
Certificate fingerprint (SHA1): 29:18:8E:DA:B1:58:2C:D4:C0:56:90:A2:9F:B4:0A:72:FB:C6:9A:67

The alias in this case is "mycert". Rename to the correct alias name, e.g. spotfire.

keytool -changealias -alias "mycert" -destalias "spotfire" -keystore /path/to/keystore

 

 

Related articles

Comments

0 comments

Article is closed for comments.