How-To Set Up a Forward Proxy for Agent Communication to the Contrast UI

  • Updated


As detailed in this Support Bulletin, Contrast is in the process of deprecating support for TLS protocols below version 1.2.  This article details the steps that should be taken to ensure no interruption in traffic from the Contrast agents to the Contrast UI, however in some cases (primarily where older technology is in use) a workaround may be necessary to allow connectivity to continue.  This article details two possible workarounds via an OpenSSL forward proxy:

Nginx + Ghostunnel  using OpenSSL

(Agent) HTTP → (Proxy) HTTPS TLSv1.2 → (Contrast UI) TLSv1.2 

Squid using OpenSSL

(Set up requires need of OpenSSL supporting Cipher Suites of both Java Environment and Contrast UI)

(Agent) HTTPS TLS v1.0/1.1 → (Proxy) HTTPS TLSv1.0/1.1/1.2 → (Contrast UI) HTTPS TLSv1.2 

Requires OpenSSL to support Ciphers of JVM

Note:Contrast makes no recommendation of a specific proxy solution - support for this option would be the responsibility of the user.


Nginx + Ghostunnel  using OpenSSL


What’s happening?

  • ghostunnel is used to proxy connections from the Contrast agent on the application server over TLS to the Contrast Team Server.

  • nginx is used to facilitate this proxying by modifying the Request Host header for all traffic going out the ghostunnel proxy.

  • The Contrast agent is configured (via something like the contrast_security.yaml file) to connect over HTTP point to the localhost proxy setup. When the connection leaves the application server (via ghostunnel) it will be sent over the proxying service’s TLS connection.

Steps to set-up:

  1. Install ghostunnel via their official docs here: GitHub - ghostunnel/ghostunnel: A simple SSL/TLS proxy with mutual authentication for securing non-TLS services

    1. go is a requirement to install this, so make sure you have it installed correctly and a version greater than 1.12

    2. git clone the repo and perform the make ghostunnel command from the directory.

    3. ghostunnel can be used as a client proxy with a command similar to the following: sudo ./ghostunnel client --listen=localhost:1111 --disable-authentication

      1. NOTE: --disable-authentication prevents the need for ghostunnel to present its own certificates to display to the client. That is, our setup will have it proxying transparently.

      2. You should be able to test this working correctly with a sample curl request, like this: curl 'http://localhost:1111/Contrast' -H "Host:"

        1. Server response should redirect to the Contrast login in this scenario.

      3. You can validate that ghostunnel is connecting over TLS by running the following tcpdump command to check for TLS handshake packets:

        1. sudo tcpdump -ni eth0 "tcp port 443 and (tcp[((tcp[12] & 0xf0) >> 2)]=0x16)"

        2. Sending the above curl should generate activity on the tcpdump filter

  2. Install and config nginx to proxy requests to the ghostunnel setup.

    The simplest config looks something like this in the file /etc/nginx/sites-available/default:

    server {
    listen localhost:80; 
    root /var/www/html;
    # Add index.php to the list if you are using PHP
    index index.html index.htm index.nginx-debian.html;
    server_name _;
    location / {
    # First attempt to serve request as file, then
    # as directory, then fall back to displaying a 404.
    #try_files $uri $uri/ =404;
    proxy_pass http://localhost:1111/;
    proxy_set_header Host;
             NOTE: The only purpose this serves is to set the Host header for outgoing requests, as                there’s no way to configure the Contrast agent to do this with our setup.  You should be                able to test this part of the workflow similar to the previous test:
      1. curl "http://localhost/Contrast"

      2. Note that in this instance, we no longer need to force the Host header, and the default port in this situation is 80.

  3. Configure the Contrast agent’s contrast_security.yaml file to communicate over the proxied connection.

    1. A sample configuration may look like this:

      url: http://localhost/Contrast
      api_key: <Enter your API Key>
      service_key: <Enter your Service Key>
      user_name: <Enter the Agent User Name>

Other Notes

  • If the application (and thus, the agent) run in a container, like Docker, you may not be able to use localhost with the way Docker networking works.

    • In this case, an easy workaround is to enable ghostunnel in --unsafe-listen mode and enable it to run on to open it on all available ports.

    • Then you could configure the IP in the agent yaml file to point to the private IP of the Docker host.

  • This is a workaround/temp solution to ensure an agent continues to function. The BEST solution is to upgrade the environment so that it supports TLS 1.2 and above, and allow the agent to connect that way.

  • This is the shortest/quickest TLS proxy setup. There are undoubtedly other ways to configure these proxy settings or other modules that could be employed.

    • Why not nginx and proxy through that directly?

      • I ran into issues with upstream SSL connection between nginx and the Contrast TS that I struggled to resolve and found ghostunnel more seamless.

    • Why not squid proxy and ssl-bump with http connect?

  • All of the above are valid considerations that could absolutely be considered by customers.

  • MOST IMPORTANTLY - this is a potential solution for illustrative purposes, but customers should accept all risk of implementing such a solution, as Contrast cannot maintain a workaround solution. Especially one that strays from the best practice guideline of upgrading to something that can support the correct TLS versions

Squid with OpenSSL




Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request