Skip to main content

Connect using HTTP proxy

This guide connects the automator Proxy to the automator using your company's HTTP proxy. To keep the two apart, this guide refers to the automator Proxy as the proxy and to your company's HTTP proxy as the company proxy. The guide is only relevant when both of the following are true for your setup:

  • You use the pull transport mode, where the proxy initiates the outbound connections to the automator.
  • Outbound HTTPS in your network is only allowed through the company proxy.

Prerequisites​

  • The proxy is installed inside your network. Installing its dependencies with npm install also needs the company proxy; configure it for npm first:

    npm config set proxy http://proxy.company.local:8080

  • The URL of the company proxy, for example http://proxy.company.local:8080. When the company proxy requires authentication, include the credentials in the URL: http://user:password@proxy.company.local:8080.

Configure the company proxy​

How the company proxy is configured depends on how the proxy runs:

  • as a Windows service, registered with service_install.js,
  • as a systemd service on Linux, or
  • in the foreground, started from a shell (the example below uses PowerShell).

In all three cases, the proxy is a Node.js application, and Node.js reads the company proxy from the environment when it starts. Two environment variables need to be set:

  • HTTPS_PROXY: the URL of the company proxy.
  • NODE_USE_ENV_PROXY: set to 1, so Node.js tunnels all outbound HTTPS connections through the company proxy named in HTTPS_PROXY.

The following sections describe for each of the three cases how to set these environment variables.

Windows service​

The service installer sets both environment variables for the service when the https_proxy option is set in service_config.toml (see Configuration):

name = "techwork-automator-proxy-service"
description = "automator Proxy service"
https_proxy = "http://proxy.company.local:8080"

Then (re)register the service (see Install the proxy). The setting applies to all profiles of the service.

Linux service​

Set both environment variables in the systemd unit:

[Service]
Environment=NODE_USE_ENV_PROXY=1
Environment=HTTPS_PROXY=http://proxy.company.local:8080

Foreground​

Set both environment variables in the shell before starting the proxy, for example in PowerShell:

$env:NODE_USE_ENV_PROXY = "1"
$env:HTTPS_PROXY = "http://proxy.company.local:8080"
node execproxyserver.js

Verify the configuration​

Make sure to restart the proxy so it picks up the environment variables, then use Verify on the Proxy account form. A success confirms that the proxy reaches the automator through the company proxy; a timeout means it does not, and the proxy log should show the reason.

Troubleshooting​

Trust the company's certificate​

Some company proxies inspect TLS traffic: they terminate the HTTPS connection and re-encrypt it with a certificate issued by the company's own certificate authority. Node.js validates the automator's certificate against the standard set of trusted certificate authorities only, so the connection then fails with a certificate error:

fetch failed: self-signed certificate in certificate chain; if the root CA is installed locally, try running Node.js with --use-system-ca

In that case, additionally set NODE_USE_SYSTEM_CA to 1. Node.js then also trusts the certificate authorities in the operating system's certificate store, where the company's certificate authority is usually installed.

On Windows, add the variable to the [env] table in service_config.toml:

name = "techwork-automator-proxy-service"
description = "automator Proxy service"
https_proxy = "http://proxy.company.local:8080"

[env]
NODE_USE_SYSTEM_CA = "1"

On Linux, add Environment=NODE_USE_SYSTEM_CA=1 to the systemd unit (see Linux service).

In the foreground, add $env:NODE_USE_SYSTEM_CA = "1" to the shell commands (see Foreground).

When the company's certificate authority is not installed in the operating system's certificate store, for example on a Linux machine that is not centrally managed, NODE_USE_SYSTEM_CA has no effect. In that case, export the company's certificate authority to a PEM file and point the NODE_EXTRA_CA_CERTS environment variable to that file instead, using the same [env] table, Environment= line or shell variable.