Skip to main content

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.

You can customize the configuration further as described in icon-external-link.svgHow-To Modify Supported TLS Versions and Ciphers on On-Premise Contrast Server.

Important

In the following procedures, it is important that you use only a single password throughout. If any of the CA-provided files are password protected, you must either remove that password (your CA can help you with this) or ensure that you use the same password for the resulting JKS KeyStore file.

Use the Contrast HTTPS connector

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

Note

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

Certificate Signing Request (CSR) is required

For this situation, create the KeyStore first and then use that as the basis for the CSR.

Important

The CA provides you with files that you must import into the same KeyStore from which you generated the CSR.

  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

    Note

    When you create the KeyStore, depending on the Java version you're using, the first prompt might ask “What is your first and last name?”. Enter the Common Name (the FQDN for which the certificate will be issued). For example, use a name like mydomain.com instead of your first and last name.

  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 files into the Java KeyStore. Use these instructions depending on the file type you receive.

    • 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 

  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>, <full path to>, and <password> with your port, JKS file path,and password.

    https.enabled=true
https.port=<port>
https.keystore.file=<full path to>/contrast.jks
https.keystore.pass=<password>
https.keystore.alias=contrast-server

    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. Optional:outline_open_in_new_black_24dp.pngModify supported TLS versions and cipher suites.

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

No CSR is required

For this situation, create a new KeyStore from the files the CA provides you. If you have an existing KeyStore, delete or rename it before you create the new one.

  1. Use one of these methods to create the KeyStore:

    • If you have server.crt,priv.key and inter.crt files: Convert the files to a PKCS #12 and create a KeyStore with 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

    • If you have a PKCS #12 file: Create a KeyStore with this command.

      keytool -importkeystore -srckeystore cert.pfx -srcstoretype pkcs12 -destkeystore contrast.jks -srcalias <sourcealias> -destalias contrast-server -deststoretype jks

  2. 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>, <full path to>, and <password> with your port, JKS file path,and password.

    https.enabled=true
https.port=<port>
https.keystore.file=<full path to>/contrast.jks
https.keystore.pass=<password>
https.keystore.alias=contrast-server

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

  4. Optional:outline_open_in_new_black_24dp.pngModify supported TLS versions and cipher suites.

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

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: