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. There are two ways to do this:

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

  • Contrast HTTPS connector: Configure Contrast to listen to HTTPS connections on a port that you specify.

To use 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. In some cases, you might want to also disable the http.enabled and https.enabled options.

    The ajp.secret setting should have a non-null, non-zero length value. This is not required if secretRequired is configured to false. 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. Also refer to the following links for Apache and NGINX instructions.

To use the Contrast HTTPS connector:

  1. Make sure you have a certificate to use. The certificate can be CA signed or self-signed.

  2. Import your certificate into a new Java KeyStore (JKS) for use by Contrast. If you already have a KeyStore, you can skip this step and place it in the $CONTRAST_HOME/data/conf/ssl directory.

  3. Use the following command to generate a self-signed certificate and KeyStore, it will prompt you for information about your organization and then generate a KeyStore with a self-signed certificate.

    $ jre/bin/keytool -genkey -keyalg RSA -alias contrast-server -keystore data/conf/ssl/contrast-server.jks -validity 365 -keysize 2048

    Use this method rather than generating certificates with OpenSSL. For more complicated SSL configurations, Contrast recommends using a reverse proxy. The following section walks you through enabling SSL in the Contrast server.

  4. To import SSL certificates verified by third-party providers, generate a new KeyStore.

    $ jre/bin/keytool -genkey -alias contrast-server -keystore data/conf/ssl/contrast-server.jks
  5. Once it's created, import your server's certificate into the new KeyStore.

    $ jre/bin/keytool -import -keystore data/conf/ssl/contrast-server.jks -storepass <keystore password> \
      -file <path to certificate> -alias <server hostname>
  6. You may also need to import intermediate CA certifications into the KeyStore. (See your CA's documentation to verify that this is the case.) For a private CA server, you need any intermediate certificates and the root CA certificate in the KeyStore.

    $ jre/bin/keytool -import -trustcacerts -alias <ca-name> -storepass <keystore password> \
      -file <path to ca or intermediate certificate>

    Note

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

  7. Once KeyStore setup is complete, open the $CONTRAST_HOME/data/conf/server.properties file in your text editor, and update the properties.

    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 to listen for https connections on>
    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.

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

  9. Open the $CONTRAST_HOME/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.

    Note

    The Contrast .NET agent needs additional configuration to connect to a Contrast application using a self-signed certificate.