> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-gateway/5/configure-proxy-gateway-manager-connections/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Configure proxy for Gateway Manager connections

Itential Gateway 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.

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

This topic covers the connect proxy, which routes Gateway's outbound control-plane connection to Gateway Manager. This is separate from the per-request proxy used for integration HTTP requests, which is configured in Admin Essentials. For more information, see [Gateway configuration](/itential-platform/6/admin-essentials/gateway-configuration).

## Supported proxy types

| Proxy type  | Supported | Notes                                   |
| ----------- | --------- | --------------------------------------- |
| HTTP proxy  | Yes       | Standard HTTP proxy with CONNECT method |
| HTTPS proxy | Yes       | Proxy connection itself over TLS        |
| SOCKS4/5    | No        | Not currently supported                 |
| PAC files   | No        | Proxy auto-configuration not supported  |

## 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: Gateway environment variables

Set the following environment variables:

```bash
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](./gateway-connect-variables).

### Method 2: Configuration file

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

```ini
[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, Gateway checks the standard system proxy environment variables:

```bash
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"
```

Gateway checks `HTTPS_PROXY` first because it uses secure WebSocket connections (wss\://).

## Authentication

### Basic authentication

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

#### Option 1: Separate username and password

```bash
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

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

Credentials in the URL take precedence over separate username and password settings.

### 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:
  ```bash
  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

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

### Example 2: Authenticated proxy with environment variables

```bash
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`:

```ini
[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 Gateway:

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

### Example 4: System proxy settings

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

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

# Gateway automatically uses the system proxy
iagctl server
```

## Verification

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

```bash
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

**Issue:** Gateway fails to connect to Gateway Manager.

**Steps to diagnose:**

1. Verify that the proxy server is reachable:
   ```bash
   curl -x http://proxy.example.com:8080 https://gateway-manager.example.com
   ```

2. Check the Gateway logs for proxy-related errors:
   ```bash
   tail -f /var/log/gateway/gateway.log | grep -i proxy
   ```

3. To rule out TLS certificate issues, temporarily enable insecure TLS:
   ```bash
   export GATEWAY_CONNECT_INSECURE_TLS=true
   ```

### Authentication failures

**Issue:** 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

**Issue:** 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

**Issue:** You see certificate verification errors.

Gateway 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`.