Configure HTTPS

By default, HTTP is used for connections between Contrast and the agents. You may need to add or replace HTTP with HTTPS for both Contrast and agent traffic, which you can do with Tomcat's built in connector functionality. There are two ways to do this:

  • Contrast HTTPS connector: Configure Contrast to listen to HTTPS connections on a port that you specify by adding a certificate to a Java KeyStore.

  • Reverse proxy method: Use a standard web server, such as Apache HTTPD or NGINX, in front of the Contrast server configured to reverse proxy requests using Contrast's AJP connector.

Use the Contrast HTTPS Connector

Use these steps to create a Java KeyStore (JKS), with a signed certificate, that your on-premises Contrast application server will use at runtime.

  1. Use the Java keytool command to create a Java KeyStore (JKS) (for example, contrast.jks) containing a private and public key for a certificate with an alias of contrast-server.

    keytool -genkeypair -alias contrast-server -keyalg RSA -keystore contrast.jks

  2. Generate a Certificate Signing Request (CSR) (contrast.csr). You can add DNS or IP fields as needed to include these as Subject Alternative Names on the certificate.

    keytool -certreq -alias contrast-server -file contrast.csr -keystore contrast.jks -ext san=dns:your_hostname.your_company.com,ip:10.0.0.1

  3. Send the resulting CSR file to your CA. The CA will provide you with either multiple PEM files or a single PCKS #7 file.

  4. Import the file(s) into the Java KeyStore. Use these instructions depending on the file type you receive.

    Note

    In order for Contrast to use the SSL Certificate, the certificate can't be protected with a passphrase.

    • Multiple PEM files: These files have extensions of .CRT or .PEM (PEM files open as readable text). One file contains the certificate, while the others contain the root and possibly one or more intermediate certificates. 

      The certificates must be imported into the KeyStore in a top-down order, with the server certificate itself being imported last. The server certificate should have the same alias used when the KeyStore was created.  For example, if you were provided with root.cer, inter.cer and server.cer, you should import them as:

      keytool -import -trustcacerts -alias root -file root.cer -keystore contrast.jks
keytool -import -trustcacerts -alias intermediate -file inter.cer -keystore contrast.jks
keytool -import -trustcacerts -alias contrast-server -file server.cer -keystore contrast.jks

    • Single PCKS #7 file: This file has an extension of .P7B, .CER or possibly .CRT. This file contains the server certificate bundled with all necessary root and intermediate certificates. The server certificate should have the same alias used when the KeyStore was created. For example, for a file certificate.p7b, import it as:

      keytool -import -trustcacerts -alias contrast-server -file certificate.p7b -keystore contrast.jks 

    Note

    If you retrieve your certificates through another method, you may need to create a keystore differently. For example, if you end up with a:

    • server.crt,priv.key and inter.crt files: Convert the files to a PKCS #12 and create a keystore using these commands.

      openssl pkcs12 -export -out cert.pfx -inkey priv.key -in server.crt -certfile inter.crt -name "contrast-server"
keytool -importkeystore -srckeystore cert.pfx -srcstoretype pkcs12 -destkeystore contrast.jks -deststoretype jks

    • PKCS #12 file: Create a keystore with this command.

      keytool -importkeystore -srckeystore cert.pfx -srcstoretype pkcs12 -destkeystore contrast.jks -deststoretype jks

  5. Once KeyStore setup is complete, open the <YourPath>/data/conf/server.properties file in your text editor, where <YourPath> is the path where Contrast is installed.

    Replace <port>, <file>, <password>, <hostname> with your port, JKS file path, password, and the hostname alias given in the keytool command.

    https.enabled=true
https.port=<port>
https.keystore.file=<file>
https.keystore.pass=<password>
https.keystore.alias=<hostname>

    Important

    If using Windows, the full path to the JKS file must be escaped. For example:

    https.keystore.file=C:\\Program\ Files\\Contrast\\data\\conf\\ssl\\contrast-server.jks

    You may find it useful to set the http.enabled and ajp.enabled options to false to ensure that only connections made over HTTPS are allowed to the Contrast server.

  6. Open the <YourPath>/data/conf/general.properties file, and change the value of the teamserver.url property to reflect your change. Agents must be updated manually the first time after you make this change. Future updates to the agent will be automatic.

  7. Restart the Contrast server service, and ensure that it's now listening on the HTTPS port you configured.

Note

It is also possible to use the HTTPS connector with a self-signed certificate.

Use the reverse proxy method

To use Apache JServ Protocol (AJP) with the reverse proxy method:

  1. Ensure that the Contrast server is configured to listen for connections using the AJP protocol. Open the CONTRAST_HOME/data/conf/server.properties file in your text editor and verify that the following options are set:

    ajp.enabled=true
ajp.port=8009
ajp.secretRequired=true|false
ajp.secret=somesecret

    Choose the ajp.port setting to reflect the port on which you'd like the server to listen for incoming connections. If you want the AJP connector to be the only way to access the server, disable the http.enabled and https.enabled options.

    If the secretRequired is configured to true, the ajp.secret setting should have a non-null, non-zero length value. Request workers are required to have the secret keyword; otherwise, the requests are rejected. The workers must provide a matching value, or the request will be rejected regardless of the setting of secretRequired.

  2. After updating the server.properties file, restart the Contrast server service for the changes to take effect.

  3. To configure the front-end server, refer to your server's documentation for instructions on how to configure it to use AJP. (For example, see Apache or NGINX AJP documentation.)

In this section: