Enabling HTTPS - 3.12

Using a self-signed .cer certificate file

HTTPS can be setup with a .cer certificate file. The following example details the steps required to create a self-signed .cer certificate file, and then use it to configure HTTPS for Analyze.

You may already have your own .cer file, in which case you can leave out Step 4, and repeat Step 5 to add your .cer file to both the cacerts keystore (detailed in step 5) and the keystore you created in Step 2.

1. Stop all Data360 Analyze services. See Starting and stopping the Data360 Analyze Server.
2. Create a keystore using keytool:

   <Data360Analyze installation directory>jre\bin\keytool

   -genkey -alias tomcat -keyalg RSA -keypass changeit -storepass changeit -storetype JKS - keystore keystore.jks -dname "CN=example.com,OU=Dev,O=MyCorp,L=Windermere,S=Cumbria,C=GB" -ext san=dns:example.com,ip:127.0.0.1

3. After running the above command, you will be asked to enter information relating to the self signed certificate, as in the following example:
   Tip: You should replace the details in this example as required. In particular, note that when you are asked to provide a "first and last name", this needs to map to your domain name.

   Enter keystore password:Re-enter new password:What is your first and last name?[Unknown]: localhostWhat is the name of your organizational unit?[Unknown]: DevWhat is the name of your organization?[Unknown]: CompanyWhat is the name of your City or Locality?[Unknown]: LimerickWhat is the name of your State or Province?[Unknown]: MunsterWhat is the two-letter country code for this unit?[Unknown]: IE

4. Extract the certificate:

   <installation-dir>\jre\bin\keytool

   -export -alias tomcat -storepass changeit -file selfsignedcert.cer -keystore keystore.jks

5. Add the certificate to the cacerts keystore of the bundled jre:

   <installation-dir>\jre\bin\keytool -import -v -trustcacerts -alias tomcat -file selfsignedcert.cer -keystore "<Data360 Analyzesite directory>/cust-keystores/cacerts" -keypass changeit

   Tip: If for any reason you need to repeat these steps, you first need to make a copy of the cacerts file, then remove the previously created keystore.jks and selfsignedcert.cer files.
   Note: Should you wish to alter the alias, the imported alias can be changed using this command:

   keytool -changealias -alias "1" -destalias "analyze"
               -keystore keystore.jks

6. Copy the keystore.jks created in step 2 to:

   <Data360 Analyze site directory>/cust-keystores

7. Navigate to the Tomcat server-cust-connectors.xml located at:

   <Data360 Analyze site directory>/conf/tomcat/server-cust-connectors.xml

   Add the following text to the server-cust-connectors.xml file:

   <Connector protocol="org.apache.coyote.http11.Http11NioProtocol"

   port="8443" maxThreads="200"

   scheme="https" secure="true" SSLEnabled="true"

   keystoreFile="<Data360 Analyze site directory>/cust-keystores/keystore.jks" keystorePass="changeit"

   clientAuth="false" sslProtocol="TLSv1.2" sslEnabledProtocols="TLSv1.2" compression="on"

   compressableMimeType="text/html,text/xml,text/plain,text/css,text/javascript,application/javascript,application/json"/>

   Note: The keyStoreFile value must be replaced with the location of the keystore.jks file in Step 6.

   If you are using a port number other than 8443, change the redirectPort number on this line:

   <Connector connectionTimeout="20000" port="8080" protocol="HTTP/1.1" redirectPort="8443"/>

   Note: In Linux, any port below 1024, for example port 443, will be restricted and not available by default. Using port 443 will require root access and an additional step on the operating system.
8. Open the following file for editing:

   <Data360 Analyze site directory>/conf/tomcat/web-cust.xml

9. Add the following text to web-cust.xml.

   No changes are needed to the values below:

   <security-constraint>

   <web-resource-collection>

   <web-resource-name>Entire Application</web-resource-name>

   <url-pattern>/*</url-pattern>

   </web-resource-collection>

   <user-data-constraint>

   <transport-guarantee>CONFIDENTIAL</transport-guarantee>

   </user-data-constraint>

   </security-constraint>

   Tip: You can find additional information regarding Tomcat changes at https://tomcat.apache.org/tomcat-8.5-doc/ssl-howto.html#Configuration
10. Open the following file for editing:

    <Analyze site directory>/conf/cust.prop

11. Within cust.prop, add the following text and update the localhost to the actual Analyze server name, and the port to the value specified within <Data360 Analyze site directory>/conf/tomcat/server-cust-connectors.xml:

    ls.brain.webapp.contextUrl=https://localhost:8443/

12. Start the Data360 Analyze services. See Starting and stopping the Data360 Analyze Server.

With a .pfx certificate file

HTTPS can be setup using your own .pfx certificate file. Do the following:

1. Stop all Data360 Analyze services. See Starting and stopping the Data360 Analyze Server.
2. Open a command prompt, or a terminal session and navigate to:

   <Data360Analyze installation directory>/jre/bin

3. Import the certificate into Analyze's embedded Java cacerts.
   Note: The following sample command needs to be updated with your destination store password (changeit) and the destination keystore location, within your actual Analyze installation (-destkeystore). The source keystore (-srckeystore) should be updated with your PKCS12 key location.

   keytool -importkeystore -deststorepass changeit -destkeystore "<Data360 Analyze site directory>/cust-keystores/cacerts" -srckeystore "certwithkey.pfx" -srcstoretype PKCS12

4. Import the certificate into a new keystore.

   The command will create the keystore if it doesn't exist already.

   Note: The following sample command needs to be updated with your destination store password (changeit) and the destination keystore location, within your actual Analyze installation (-destkeystore keystore.jks). The source keystore (-srckeystore) should be updated with your PKCS12 key location.

   keytool -importkeystore -deststorepass changeit -deststoretype PKCS12 -destkeystore keystore.jks -srckeystore "certwithkey.pfx" -srcstoretype PKCS12

5. Run the following command:

   keytool -list -keypass changeit -storepass changeit -keystore keystore.jks

   Make note of the newly imported key's alias for a future step. Your key may have an auto-generated alias, similar to a UUID, or a name. The bold value below is the location of the alias:

   te-004ac672-f945-60e1-9529-ac97fc3c96a3, Dec 30, 2019, PrivateKeyEntry,

   Certificate fingerprint (SHA1): 44:95:FF:C6:AA:DD:D5:53:97:11:22:33:44:55:66:77:88:99:00:AA

   Note: Should you wish to alter the alias, the imported alias can be changed using this command:

   keytool
               -changealias -alias "1" -destalias "analyze" -keystore
         keystore.jks

6. Copy the keystore.jks created in step 4 to:

   <Data360 Analyze site directory>/cust-keystores

7. Navigate to the Tomcat server-cust-connectors.xml located at:

   <Data360 Analyze site directory>/conf/tomcat/server-cust-connectors.xml

8. Add the following text to the server-cust-connectors.xml file.

   Update the keyAlias and keyPass parameters with your actual values. Note that the keyStoreFile value must be replaced with the location of the keystore.jks file in Step 6.

   You may also optionally update the port value to 443 or another appropriate port.

   Note: the alias in the server.xml, refers to the certificate's alias name, rather than the name of the server(s) within the certificate. The certificate may contain 10 aliases for an Analyze server, but the certificate itself will always refer to itself by just one alias. For a self-signed certificate, users can control this alias, while for a CA-signed certificate, it is an automatically generated string+UUID.

   <Connector protocol="org.apache.coyote.http11.Http11NioProtocol"

   port="8443" maxThreads="200" keyAlias="myKeyAlias" keyPass="myKeyPass"

   scheme="https" secure="true" SSLEnabled="true"

   keystoreFile="<Data360 Analyze site directory>/cust-keystores/keystore.jks" keystorePass="changeit"

   clientAuth="false" sslProtocol="TLSv1.2" sslEnabledProtocols="TLSv1.2" compression="on"

   compressableMimeType="text/html,text/xml,text/plain,text/css,text/javascript,application/javascript,application/json"/>

9. Open the following file for editing:

   <Data360 Analyze site directory>/conf/tomcat/web-cust.xml

10. Add the following text web-cust.xml.

    No changes are needed to the values below:

    <security-constraint>

    <web-resource-collection>

    <web-resource-name>Entire Application</web-resource-name>

    <url-pattern>/*</url-pattern>

    </web-resource-collection>

    <user-data-constraint>

    <transport-guarantee>CONFIDENTIAL</transport-guarantee>

    </user-data-constraint>

    </security-constraint>

11. Open the following file for editing:

    <Data360Analyze site directory>/conf/cust.prop

12. Within cust.prop, add the following text and update the localhost to the actual Analyze server name, and the port to the value specified within <Data360 Analyze site directory>/conf/tomcat/server-cust-connectors.xml:

    ls.brain.webapp.contextUrl=https://localhost:8443/

13. Start the Data360 Analyze services. See Starting and stopping the Data360 Analyze Server.