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

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

set JAVA_HOME=C:\Program Files\Java\jdk1.8.0_162
set PATH=%JAVA_HOME%\bin;%PATH%

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

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

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

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>    	

At the end restart AnalystConnect service.

5. Let’s test it!

https://YOUR_SSA_HOST_NAME:8443/connect/analyst.

You will see the Spectrum Spatial Analyst login page.