Proxy configuration for Gateway Manager connections

Itential Automation Gateway (IAG) supports routing connections to Gateway Manager through HTTP/HTTPS proxy servers. This is useful in enterprise environments where direct internet access is restricted and all outbound connections must go through a corporate proxy.

Overview

When you enable proxy support, IAG establishes a secure WebSocket connection (wss://) to Gateway Manager through your configured proxy server using the HTTP CONNECT tunneling method. IAG establishes the TLS connection after the proxy tunnel, which ensures end-to-end encryption.

Configuration methods

You can configure proxy settings using three methods, listed here in order of precedence:

1. Environment variables (highest priority)
2. Configuration file
3. System proxy environment variables (fallback)

Method 1: IAG environment variables

Set the following environment variables:

export GATEWAY_CONNECT_PROXY_URL="http://proxy.example.com:8080"
export GATEWAY_CONNECT_PROXY_USERNAME="myuser"
export GATEWAY_CONNECT_PROXY_PASSWORD="mypassword"

For more information, see Connect variables.

Method 2: Configuration file

Add proxy settings to your IAG configuration file (~/.gateway.d/gateway.conf or /etc/gateway/gateway.conf):

[connect]
enabled = true
hosts = gateway-manager.example.com:443
certificate_file = /etc/gateway/certificates/gw-manager.pem
private_key_file = /etc/gateway/certificates/gw-manager-key.pem

# Proxy configuration
proxy_url = http://proxy.example.com:8080
proxy_username = myuser
proxy_password = mypassword

Method 3: System environment variables (fallback)

If you don't provide explicit proxy configuration, IAG checks the standard system proxy environment variables:

export HTTPS_PROXY="http://proxy.example.com:8080"
# or
export https_proxy="http://proxy.example.com:8080"
# or
export HTTP_PROXY="http://proxy.example.com:8080"
# or
export http_proxy="http://proxy.example.com:8080"

Authentication

Basic authentication

IAG supports HTTP Basic Authentication for proxy servers. You can provide credentials in two ways.

Option 1: Separate username and password

export GATEWAY_CONNECT_PROXY_URL="http://proxy.example.com:8080"
export GATEWAY_CONNECT_PROXY_USERNAME="myuser"
export GATEWAY_CONNECT_PROXY_PASSWORD="mypassword"

Option 2: Embedded in proxy URL

export GATEWAY_CONNECT_PROXY_URL="http://myuser:mypassword@proxy.example.com:8080"

Security best practices

• Prefer environment variables. Store proxy credentials in environment variables rather than configuration files to avoid committing secrets to version control.
• Set file permissions. If you must store credentials in a configuration file, set proper file permissions:

  chmod 600 ~/.gateway.d/gateway.conf
  

• Use a secrets management system. In production environments, use a secrets management system (such as HashiCorp Vault or AWS Secrets Manager) to inject proxy credentials as environment variables.

Configuration examples

Example 1: Unauthenticated proxy

export GATEWAY_CONNECT_PROXY_URL="http://proxy.corp.example.com:8080"
iagctl server

Example 2: Authenticated proxy with environment variables

export GATEWAY_CONNECT_PROXY_URL="http://proxy.corp.example.com:8080"
export GATEWAY_CONNECT_PROXY_USERNAME="john.doe"
export GATEWAY_CONNECT_PROXY_PASSWORD="secure-password-123"
iagctl server

Example 3: Authenticated proxy with a configuration file

Create /etc/gateway/gateway.conf:

[connect]
enabled = true
hosts = gateway-manager.itential.io:443
certificate_file = /etc/gateway/certificates/gw-manager.pem
private_key_file = /etc/gateway/certificates/gw-manager-key.pem
proxy_url = http://proxy.corp.example.com:8080
proxy_username = john.doe
proxy_password = secure-password-123

Then start IAG:

iagctl server --config /etc/gateway/gateway.conf

Example 4: System proxy settings

If your system already has proxy environment variables configured, IAG uses them automatically:

# Verify your system proxy is set
echo $HTTPS_PROXY
# Output: http://proxy.corp.example.com:8080

# IAG automatically uses the system proxy
iagctl server

Verification

To verify that IAG loaded your proxy configuration correctly, run:

iagctl version --show-config

Look for the connect_proxy_url field in the output. The output displays the proxy username but redacts the password for security.

Troubleshooting

Connection failures

Symptom: IAG fails to connect to Gateway Manager.

Steps to diagnose:

1. Verify that the proxy server is reachable:

   curl -x http://proxy.example.com:8080 https://gateway-manager.example.com
   

2. Check the IAG logs for proxy-related errors:

   tail -f /var/log/gateway/gateway.log | grep -i proxy
   

3. To rule out TLS certificate issues, temporarily enable insecure TLS:

   export GATEWAY_CONNECT_INSECURE_TLS=true
   

Authentication failures

Symptom: You see an error message that mentions "407 Proxy Authentication Required."

Steps to resolve:

1. Verify that your credentials are correct.
2. Check whether special characters in the password need URL encoding.
3. Try providing credentials in URL format: http://user:pass@proxy:8080.

Proxy refuses connection

Symptom: You see an error message that mentions "403 Forbidden" or "connection refused."

Possible causes:

• The proxy doesn't allow the CONNECT method to the destination host or port.
• The proxy policy blocks the destination host.
• The proxy doesn't authorize the source IP.

Steps to resolve:

• Contact your network or proxy administrator to add Gateway Manager hosts to the allowlist.
• Confirm that the proxy allows the CONNECT method to port 443.

TLS certificate issues

Symptom: You see certificate verification errors.

IAG validates the Gateway Manager certificate, not the proxy certificate. The proxy acts as a transparent tunnel for the TLS connection.

Steps to resolve:

• Make sure your system CA certificates are up to date.
• Verify that the Gateway Manager certificate is valid.
• If you use a custom CA, configure GATEWAY_APPLICATION_CA_CERTIFICATE_FILE.

Supported proxy types