Appendix A- Configuring HTTPS Communication for Spectrum Spatial Analyst

This appendix describes how to configure Spectrum Spatial Analyst to use HTTPS communications for end users browsing to the application. Communications between Spectrum Spatial Analyst and the back-end Spectrum Services can remain on HTTP if desired. If these are to be configured for HTTPS also then please see Appendix B- Configuring HTTPS Communication with Spectrum Spatial.

The default supported channel for an initial Spectrum Spatial Analyst installation is HTTP, but you can configure Spectrum Spatial Analyst to use HTTPS if you are concerned about security. This ensures that the data being sent is encrypted by one side, transmitted, and then decrypted by the other side before processing.

To configure Spectrum Spatial Analyst to use HTTPS communication, you first need to successfully install it and then follow these steps:

  1. Prepare a Keystore
  2. Import your site certificates
  3. Establish Trust with certificate authority
  4. Configure the Spectrum Spatial Analyst Tomcat to use the Keystore
  5. Test the Spectrum Spatial Analyst application

1. Prepare a Keystore

The first step to enabling SSL on Spectrum Spatial Analyst is to prepare a keystore. The keystore contains the keys that the Spectrum Spatial Analyst Tomcat uses for SSL transactions. Spectrum Spatial Analyst Tomcat supports only these keystore formats: JKS, PKCS11 or PKCS12. If you already have a keystore – JKS, p12, pfx file, then you can jump to step 3 - Establish trust with certificate authority. Otherwise, you need to create a certificate and get it signed by a certificate authority.

Create a new Keystore

Note: You have to replace the <placeholders> while running the commands.
Open a command line and set JAVA_HOME & PATH environment properties so that you can use keytool commands seamlessly:
set JAVA_HOME=C:\Program Files\Java\jdk1.8.0_162
set PATH=%JAVA_HOME%\bin;%PATH%
Now, execute the following command, it generates a key pair and certificate directly into a JKS keystore-
keytool -genkeypair -alias <your_alias> -keystore <ssa_keystore_name.p12> -storetype pkcs12  -keyalg RSA -validity 360 -keysize 2048  -sigalg SHA256withRSA

Enter the name of the server host in the ‘First name and Last name’ field.

You now have the minimal requirements to run a HTTPS connection and could proceed directly to configure an SSL connector. However, the browser will not trust the certificate you have generated and prompts the user to this effect. While what you have at this point is often sufficient for testing, most public sites need a trusted certificate, which is demonstrated in the section generating a Certificate Signing Request (CSR) with the Key tool.

Create a Certificate Signing Request

Substitute the values you chose earlier for the <placeholders>
keytool -certreq -alias <server_name> -keystore <ssa_keystore_name> -file <your_certificate_name>.csr

The Keytool will create a file called your_certificate_name.csr, which you can submit to the Certificate Authority you've chosen via the process they provide on their website. Using this file, they will generate a custom certificate for your server, which you can download according to the instructions they provide on their website.

2. Import your site Certificates

Once you've downloaded both your own Certificate and the Root certificate provided by your Certificate Authority, import them into your keystore with the commands specified in next sections.

Install your site Certificate

To import a certificate into a Java keystore issue the following command:
keytool -import -alias <server_name> -keystore <ssa_keystore_name> -file <certificate_file_name>

3. Establish trust with certificate authority

Install the Root Certificate

keytool -import -alias <root_ca_certificate_name> -trustcacerts -file <root_ca_certificate_file_name> -keystore "%JAVA_HOME%\jre\lib\security\cacerts"

You can verify if the certificate was imported correctly by issuing this command:

keytool -list -v -keystore "%JAVA_HOME%\jre\lib\security\cacerts" -alias <root_ca_certificate_alias>

Install the Intermediate Certificate file

This is an optional step. If your certificate authority provided an intermediate certificate file, you will need to install it here by typing the following command:

keytool -import -alias <intermediate_ca_certificate_name> -trustcacerts -file <intermediate_ca_certificate_file_name> -keystore "%JAVA_HOME%\jre\lib\security\cacerts"

4. Configuring Tomcat for using the keystore file

Open your Spectrum Spatial Analyst installation directory and go to: <installation directory>\Tomcat, you should find two tomcat installation as shown below:
  • AnalystConnect
  • AnalystLocate

The following section describes changes for configuring HTTPS for AnalystConnect tomcat only, you should follow the same steps if you want to configure Address search service on HTTPs. You have to ensure that you use unique values of “port” for each configuration, otherwise tomcat will fail to start.

First you need to stop PreciselyAnalystConnectService . After that you need to go to the directory <installation directory>\Tomcat\ AnalystConnect\conf, if you want to set HTTPs communication for Connect. Open the server.xml file.

Uncomment this section and provide values for port, certificateKeystoreFile and certificateKeystorePassword.

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol" connectionTimeout="20000"
compression="on" compressionMinSize="512" compressableMimeType="text/html,text/xml,text/plain,text/css,
application/javascript,application/json,text/json-comment-filtered"
maxThreads="200" SSLEnabled="true">
<SSLHostConfig protocols="TLSv1.2">
<Certificate certificateKeystoreFile="conf/server.p12" certificateKeystorePassword="changeit" type="RSA"/>
</SSLHostConfig>
</Connector>    	
Note: Provide values for port, certificateKeystoreFile, certificateKeystorePassword.

The same can be applied to the AnalystLocate folder to configure that for HTTPS.

At the end restart AnalystConnect service.

5. Let’s test it!

Start Tomcat service and try to access-
https://YOUR_SSA_HOST_NAME:8443/connect/analyst.

You will see the Spectrum Spatial Analyst login page.