# Proxy Configuration

## Overview <a href="#overview" id="overview"></a>

In enterprise environments, network security policies may require internet traffic to flow through a corporate proxy server. Keeper Gateway supports standard HTTP/HTTPS proxy configuration through environment variables and command-line parameters, ensuring compatibility with corporate network architectures.

When proxy support is enabled, the Gateway routes all outbound connections through the specified proxy server, including:

* WebSocket connections to Keeper servers
* HTTP/HTTPS API calls
* Health check endpoints
* Version verification requests
* TURN credential requests
* RBI (Chromium) session traffic to target web servers

{% hint style="info" %}
Proxy support is currently available for Discovery and Rotation operations. PAM connection sessions (SSH, RDP, VNC, database connections, RDP) are not supported through proxies at this time due to the complexity of WebRTC media traffic routing. WebRTC connections require direct network access or TURN server configuration.
{% endhint %}

## Supported Proxy Types <a href="#supported-proxy-types" id="supported-proxy-types"></a>

Keeper Gateway supports the following proxy configurations:

* **HTTP Proxy** - Standard HTTP proxy servers (e.g., Squid, Apache Traffic Server)
* **HTTPS Proxy** - Secure proxy connections with TLS
* **Authenticated Proxies** - Proxies requiring username/password authentication
* **Bypass Lists** - Exclude specific domains or IP addresses from proxy routing

## Configuration Methods

You can configure proxy settings using **either** environment variables **or** command-line parameters. Command-line parameters take precedence over environment variables.

### Option 1: Environment Variables

Environment variables provide a standard way to configure proxy settings across all network-aware applications. These variables are recognized by most networking tools and libraries.

**Supported Environment Variables**

Keeper Gateway recognizes the following environment variables (in order of precedence):

1. `HTTPS_PROXY` or `https_proxy` - Primary proxy configuration (recommended)
2. `HTTP_PROXY` or `http_proxy` - Fallback proxy configuration
3. `NO_PROXY` or `no_proxy` - Bypass list for excluded hosts

{% hint style="info" %}
These are standard environment variable names used across many applications and programming languages. The Keeper Gateway follows this industry convention for seamless integration with existing infrastructure.
{% endhint %}

#### **Setting Environment Variables**

**Linux/macOS:**

```bash
export HTTPS_PROXY="http://proxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1,.local"
```

**Windows (Command Prompt):**

```cmd
set HTTPS_PROXY=http://proxy.company.com:8080
set NO_PROXY=localhost,127.0.0.1,.local
```

**Windows (PowerShell):**

```powershell
$env:HTTPS_PROXY="http://proxy.company.com:8080"
$env:NO_PROXY="localhost,127.0.0.1,.local"
```

**With Authentication**

Include credentials in the proxy URL:

```bash
export HTTPS_PROXY="http://username:password@proxy.company.com:8080"
```

{% hint style="info" %}
Special characters in passwords must be URL-encoded. For example, `p@ssw0rd` becomes `p%40ssw0rd`.
{% endhint %}

### Option 2: Command-Line Parameters

Command-line parameters provide additional flexibility and override environment variables when both are present.

**Available Parameters**

<table><thead><tr><th width="162.43359375">Parameter</th><th width="295.1875">Description</th><th>Example</th></tr></thead><tbody><tr><td><code>--proxy-url</code></td><td>Complete proxy URL with optional credentials</td><td><code>http://proxy.company.com:8080</code></td></tr><tr><td><code>--proxy-host</code></td><td>Proxy server hostname or IP address</td><td><code>proxy.company.com</code></td></tr><tr><td><code>--proxy-port</code></td><td>Proxy server port number</td><td><code>8080</code></td></tr><tr><td><code>--proxy-username</code></td><td>Authentication username (if required)</td><td><code>myuser</code></td></tr><tr><td><code>--proxy-password</code></td><td>Authentication password (if required)</td><td><code>mypassword</code></td></tr><tr><td><code>--no-proxy</code></td><td>Comma-separated list of hosts to bypass</td><td><code>localhost,127.0.0.1,.internal</code></td></tr></tbody></table>

## Docker Deployment with Proxy

When deploying Keeper Gateway in Docker, configure proxy settings in your `docker-compose.yml` file.

#### Docker Compose Configuration <a href="#docker-compose-configuration" id="docker-compose-configuration"></a>

Add proxy environment variables to your Gateway service:

<pre class="language-yaml"><code class="lang-yaml">services:
  keeper-gateway:
    platform: linux/amd64
    image: keepersecurityinc/gateway:latest
    environment:
      GATEWAY_CONFIG: &#x3C;your-gateway-config>

      # Proxy Configuration
<strong>      HTTP_PROXY: http://proxy:3128
</strong><strong>      HTTPS_PROXY: http://proxy:3128
</strong><strong>      NO_PROXY: localhost,127.0.0.1,db-mysql,server-ssh,server-rdp
</strong>
    networks:
      - internal-network
    depends_on:
      - proxy
</code></pre>

{% hint style="info" %}
The proxy server must be accessible from the Gateway container. If using an external proxy, ensure network connectivity. If deploying a proxy container in the same Docker Compose stack, include it in the depends\_on section.
{% endhint %}

#### Air-Gapped Docker Environment Example <a href="#air-gapped-docker-environment-example" id="air-gapped-docker-environment-example"></a>

For complete network isolation, deploy the Gateway with a dedicated proxy container:

<pre class="language-yaml"><code class="lang-yaml">networks:
  # Internal network with NO internet access
  airgapped-internal-network:
    internal: true
    ipam:
      config:
        - subnet: 10.99.0.0/24

  # Public network (proxy only)
  public-internet-network:
    driver: bridge

services:
  # HTTP Proxy (bridges networks)
  proxy:
    platform: linux/amd64
    image: ubuntu/squid:latest
    networks:
      - airgapped-internal-network
      - public-internet-network
    ports:
      - "3128:3128"
    volumes:
      - ./squid.conf:/etc/squid/squid.conf:ro

  # Keeper Gateway (air-gapped)
  keeper-gateway:
    platform: linux/amd64
    image: keepersecurityinc/gateway:latest
    environment:
      GATEWAY_CONFIG: &#x3C;your-gateway-config>
<strong>      HTTP_PROXY: http://proxy:3128
</strong><strong>      HTTPS_PROXY: http://proxy:3128
</strong><strong>      NO_PROXY: localhost,127.0.0.1,internal-service
</strong>    networks:
      - airgapped-internal-network  # NO public-internet-network
    depends_on:
      - proxy
</code></pre>

In this configuration:

* Gateway container has **no direct internet access** (only on `internal: true` network)
* All internet traffic **must** flow through the proxy container
* Proxy container bridges the air-gapped and public networks
* Internal services (databases, application servers) bypass the proxy

## Configuration Priority

When multiple configuration sources are present, Keeper Gateway applies settings in the following priority order (highest to lowest):

1. Individual command-line parameters (`--proxy-host`, `--proxy-port`, etc.)
2. `--proxy-url` command-line parameter
3. `HTTPS_PROXY` environment variable
4. `https_proxy` environment variable
5. `HTTP_PROXY` environment variable
6. `http_proxy` environment variable

For bypass lists:

1. `--no-proxy` command-line parameter
2. `NO_PROXY` environment variable
3. `no_proxy` environment variable

### Proxy URL Format <a href="#proxy-url-format" id="proxy-url-format"></a>

Proxy URLs follow standard URI syntax:

```
[scheme://][username:password@]hostname:port
```

#### Examples <a href="#examples" id="examples"></a>

**Basic HTTP proxy:**

```
http://proxy.company.com:8080
```

**HTTPS proxy:**

```
https://proxy.company.com:8080
```

**Authenticated proxy:**

```
http://username:password@proxy.company.com:8080
```

**Proxy with special characters in password:**

```
http://user:p%40ssw0rd%21@proxy.company.com:8080
```

> **Note:** URL-encode special characters in usernames and passwords using percent-encoding (e.g., `@` becomes `%40`, `!` becomes `%21`).

### NO\_PROXY Bypass List <a href="#no_proxy-bypass-list" id="no_proxy-bypass-list"></a>

The `NO_PROXY` setting allows you to exclude specific hosts from proxy routing. This is useful for:

* Internal services on the same network
* Local resources that don't require proxy access
* Services that cannot work through a proxy

#### Bypass List Format <a href="#bypass-list-format" id="bypass-list-format"></a>

The bypass list is a comma-separated list of:

* **Exact hostnames:** `localhost`, `internal-server`
* **IP addresses:** `127.0.0.1`, `192.168.1.100`
* **Domain suffixes:** `.internal.com`, `.local` (matches all subdomains)

#### Examples <a href="#examples-1" id="examples-1"></a>

**Basic bypass list:**

```bash
NO_PROXY=localhost,127.0.0.1
```

**With domain suffixes:**

```bash
NO_PROXY=localhost,127.0.0.1,.corp.internal,.local
```

**Docker internal services:**

```bash
NO_PROXY=localhost,127.0.0.1,db-mysql,server-ssh,server-rdp,server-vnc
```

{% hint style="info" %}
Spaces are automatically trimmed. Both `localhost, 127.0.0.1` and `localhost,127.0.0.1` work identically.
{% endhint %}

### Verification and Testing <a href="#verification-and-testing" id="verification-and-testing"></a>

#### Step 1: Verify Configuration <a href="#step-1-verify-configuration" id="step-1-verify-configuration"></a>

After starting the Gateway with proxy configuration, check the logs for confirmation:

```
INFO - Applying proxy configuration: proxy.company.com:8080
INFO - Using proxy for WebSocket: proxy.company.com:8080
```

#### Step 2: Test Proxy Connectivity <a href="#step-2-test-proxy-connectivity" id="step-2-test-proxy-connectivity"></a>

Before starting the Gateway, verify proxy accessibility:

**Linux/macOS:**

```bash
curl -x http://proxy.company.com:8080 https://keepersecurity.com
```

**Windows (PowerShell):**

```powershell
Invoke-WebRequest -Uri https://keepersecurity.com -Proxy http://proxy.company.com:8080
```

If the proxy requires authentication:

```bash
curl -x http://username:password@proxy.company.com:8080 https://keepersecurity.com
```