Appendix H- Configuring HTTPS Communication for SSA

This appendix describes how to configure SSA to use HTTPS communications for end users browsing to the application. Communications between SSA 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 H.

The default supported channel for an initial SSA installation is HTTP, but you can configure SSA 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 SSA to use HTTPS communication, you first need to successfully install it and then follow these steps:

Prepare a certificate Keystore.
Configure the SSA Tomcat to use the Keystore.
Modify the base URLs in shared.properties.
Test the SSA application.

Prepare a Keystore file using Java

The keys that the SSA Tomcat uses for SSL transactions are stored in a password-protected file called, the "Keystore." The first step to enabling SSL on SSA is to create and edit this file. You can create this file in one of two ways- by importing an existing key into the keystore, or by creating an entirely new key. In the interest of simplicity, this guide will only cover the later.

Note: You have to replace the [placeholders] while running the commands.

Create a new Keystore

The following command generates a key pair and certificate directly into file keystore:

"%JAVA_HOME%/bin/keytool"-genkey -alias [youralias] -keyalg RSA -keystore [/preferred/keystore/path] -keysize 2048

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

Create a Certificate Signing Request

Substitute the values you chose earlier for the [placeholders]

"%JAVA_HOME%/bin/keytool" -certreq -keyalg RSA -alias [youralias] -file [yourcertificatname].csr -keystore [path/to/your/keystore]

The Keytool will create a file called yourcertificatename.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.

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

Install the Root Certificate

"%JAVA_HOME%/bin/keytool" -import -alias root -keystore [path/to/your/keystore] -trustcacerts -file [path/to/the/root_certificate]

Install the Intermediate Certificate file:

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

"%JAVA_HOME%/bin/keytool" -import -alias intermediate -file [path/to/the/intermediate_certificate]  -trustcacerts -keystore [path/to/your/keystore]

Install your site Certificate

"%JAVA_HOME%/bin/keytool"  -import -alias [youralias] -keystore [path/to/your/keystore] -file [path/to/your_certificate]

Configuring Tomcat for using the keystore file

Open your SSA installation directory and go to: <installation directory>\Tomcat7, you should find three tomcat installation as shown below:

AnalystAdmin
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 SSA admin console/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.

You need to go to the director <installation directory>\Tomcat7\ AnalystConnect\conf, if you want to set HTTPs communication for Connect. Open the server.xml file. Find the following declaration:

<!--
<Connector port="8443" protocol="org.apache.coyote.http11.Http11Protocol"
maxThreads="150" SSLEnabled="true" scheme="https" secure="true"
clientAuth="false" sslProtocol="TLS" />
 -->

Uncomment it and modify it to look like the following:

<Connector port="8443" protocol="org.apache.coyote.http11.Http11Protocol"
maxThreads="150" SSLEnabled="true" scheme="https" secure="true"
clientAuth="false" sslProtocol="TLS"
keystoreFile="PATH_TO_YOUR_KEYSTORE" keystorePass="PASSWORD_OF_YOUR_KEYSTORE" />

Note: We add the keystoreFile, keystorePass declarations.

The same can be applied to the AnalystAdmin and AnalystLocate folders to configure these for HTTPS.

Modify the shared.properties file

If you are setting up HTTPS communication for admin console tomcat you also have to change the base URL to reflect the protocol and port. This step is not required for the AnalystConnect or the AnalystLocate tomcats. Change the property adminconsole.externalUrl

adminconsole.externalUrl = https://YOUR_SSA_HOST_NAME:HTTPS_PORT/adminconsole

Where the value of HTTPS_PORT is 8443.

Let’s test it!

Start tomcat service and try to access https://YOUR_SSA_HOST_NAME:8443/connect/analyst. You will see the SSA login page.