HTTP CONNECT forward proxy

In corporate networks, NGINX Plus R36 and later can be configured as a forward proxy server, facilitating client access to external resources. A forward proxy operates between internal clients and the global network, enabling centralized traffic control.

Unlike a reverse proxy that protects servers, upstreams, or services, forward proxy serves client requests and regulates their access to the external resources. To enable this functionality, the HTTP CONNECT method is used to establish a secure tunnel between the client and the proxy server (NGINX Plus). This tunnel permits the transmission of HTTPS traffic and other protocols, such as SSH or FTP, through the proxy.

Enable HTTP CONNECT proxy

To enable the HTTP CONNECT forward proxy, add the tunnel_pass directive that turns on the forward proxy functionality within the server or location blocks.

The tunnel_pass directive can be used without any parameters. The default value is $host:$request_port variables: all requests are automatically forwarded to external resources based on the host and the port which we are trying to access.

The tunnel_pass directive is a content handling directive (similar to proxy_pass), and if specified for the server block, will not be inherited by corresponding location blocks. If you have a location that implements any other NGINX Plus capabilities within the forward proxy, you will need to enable the tunnel_pass for this location as well. See Disable other HTTP methods.

nginx
server {
    listen 10.10.1.11:3128;

    tunnel_pass;
}

In this basic configuration, the client establishes a tunnel with NGINX Plus, sends the HTTP CONNECT method to the specified port 3128 which is standard for forward proxying, and if successful, responds with 200 OK. The tunnel is established and the client can perform the TLS handshake and get the response.

Disable other HTTP methods

As soon as the CONNECT method is enabled, all other methods such as GET, POST are not applicable in this mode. Rejecting them ensures that only tunnel requests are allowed thus improving security.

You can create a rule with the if directive to deny all HTTP methods except CONNECT, If a client uses any other method, NGINX Plus returns the 403 error code:

nginx
server {
    listen 10.10.1.11:3128;

    # Handle other methods
    location / {
        if ($request_method != CONNECT) {
            return 403 "Forbidden: allows only CONNECT method";
        }

    # allow CONNECT requests
    tunnel_pass;
    }
}

Note that in the example the tunnel_pass directive is specified inside the location block. Since tunnel_pass is a content handling directive, when it is specified for the server block, it is not inherited by nested locations.

Enable logging

For testing, debugging and monitoring purposes you can configure error and access logs.

  1. On the http level, specify the log_format directive, give the log a name (for example, http_connect), and include the metrics:

    nginx
    log_format http_connect  '$remote_addr [$time_local] '
                         '$request_method $host:$request_port $status '
                         '$upstream_addr $bytes_sent $upstream_connect_time '
                         '$request_time "$http_user_agent"';

    See the NGINX variables index for the list of all supported variables.

  2. Specify the error_log and access_log directives on the same configuration level where the tunnel_pass directive is defined:

    nginx
    access_log logs/connect_access.log http_connect;
error_log  logs/connect_error.log;

Test the configuration

This example sums up the steps above: it enables logging for the location block which denies all HTTP methods except CONNECT and where the tunnel_pass directive is specified:

nginx
log_format http_connect  '$remote_addr [$time_local] '
                         '$request_method $host:$request_port $status '
                         '$upstream_addr $bytes_sent $upstream_connect_time '
                         '$request_time "$http_user_agent"';
server {
    listen 10.10.1.11:3128;

    location / {
        if ($request_method != CONNECT) {
            return 403 "Forbidden: allows only CONNECT method";
        }

    tunnel_pass;

    access_log logs/connect_access.log http_connect;
    error_log  logs/connect_error.log;
    }
}

  1. Test NGINX configuration for syntax validity and apply the changes:

    nginx -t && nginx -s reload

  2. Send a test request with the curl command:

    curl -v -x 10.10.1.11:3128 https://example.com

  3. Check the access log to see the result of the command:

    tail -n 100 /logs/connect_access.log

    The result of the command:

    logs > connect_access.log
  1    10.10.1.240 [01/Dec/2025:10:46:27 +0000] CONNECT example.com:443 200 127.456.789.0:443 4275 0.014 0.258 "curl/8.7.1"

    The result shows that the client (10.10.1.240) successfully established a connection (200) to the destination server (example.com:443 resolved to 127.456.789.0:443).

Access control

It is highly recommended to restrict access to the proxy servers. Access control can be managed in several ways:

  • by ports and port ranges with the num_map module (NGINX Plus R36)
  • by IP addresses with the geo module
  • by hostnames with the map module

All of these access methods can be used together and combined with the the proxy_allow_upstream directive (NGINX Plus R36).

Restrict by ports and port ranges

The num_map module introduced in NGINX Plus R36 allows defining ports and port ranges and uses the same approach as the map block. For example, if the value of the $request_port variable is 443, the $allowed_port variable is assigned the value ssl. It also restricts the allowed port range for the upstream connections or proxy requests:

nginx
num_map $request_port $allowed_port {
    default    0;

    443        ssl;
    <=1023     less-eq;
    8080-8090  range;
    >8092      more;
}

Restrict by IP addresses

Access by IP addresses can be restricted with the geo module:

nginx
geo $allowed_networks {
        10.10.1.0/24  allow;
        10.20.11.0/24 allow;
        default       deny;
}

Restrict by hostnames

Restriction by hostnames can be configured with the map module, which works mainly with strings and regular expressions. Although it is possible to match port numbers using map, it is recommended to use the num_map module for more port-based restrictions, as it provides additional functionality such as defining ranges.

In this example, access is allowed to example.com and its subdomains only:

nginx
map $host  $allowed_host {
    hostnames;
    default       0;
    example.com   1;
    *.example.com 1;
}

Combine access control methods

These access methods can be combined in the tunnel_allow_upstream directive, which performs access checks when the upstream server to which the request will be sent is selected. If any variable passed to tunnel_allow_upstream evaluates to non-zero or non-empty value, it will be calculated as 1 and access is granted. If all variables evaluate to 0 or an empty value, access is denied.

Access control example

nginx
log_format connect_debug '$remote_addr [$time_local] '
                         '$request_method $host:$request_port $status '
                         '$upstream_addr $bytes_sent $upstream_connect_time '
                         '$request_time "$http_user_agent"';

num_map $request_port $allowed_port {
    default    0;

    443        ssl;
    <=1023     less-eq;
    8080-8090  range;
    >8092      more;
}

geo $allowed_networks {
        10.10.1.0/24  allow;
        10.20.11.0/24 allow;
        default       deny;
}

map $host  $allowed_host {
    hostnames;
    default       0;
    example.com   1;
    *.example.com 1;
}

server {
    listen 10.10.1.11:3128;

    #Allow CONNECT only to certain ports/nets/hosts
    tunnel_allow_upstream $allowed_networks $allowed_port $allowed_host;

    error_page 403;

    satisfy all;

    allow 10.10.0.0/16;
    allow 127.0.0.1;
    deny  all;

    tunnel_pass;

    location ^~ /errors/ {
        internal;
        root  html;
        allow all;
    }

    access_log logs/connect_access.log connect_debug;
    error_log  logs/connect_debug.log debug;
}

Access can also be limited using other modules, for example with the satisfy directive, or the allow/deny directives.

mTLS authentication

Mutual TLS (mTLS) ensures that both the client and server authenticate each other by exchanging and validating trusted certificates. Once the authentication succeeds, a secure, encrypted connection is established.

For an HTTP CONNECT proxy, mutual TLS (mTLS) is currently the only supported authentication method. Other methods, such as basic authentication are currently not supported because NGINX Plus processes only the Authorization header, not the Proxy-Authorization header.

To enable mTLS, you need:

  • a server certificate and private key, used by NGINX Plus to authenticate itself to clients
  • a client Certificate Authority (CA) certificate, used by NGINX Plus to verify client certificates
  • one or more client certificates, signed by the trusted client CA, used by clients to authenticate to the proxy
  • NGINX Plus configuration that enables TLS and enforces client certificates verification

Certificates can be created using tools such as OpenSSL or obtained from certificate providers such as Let’s Encrypt.

Configure mTLS

In your NGINX Plus configuration file:

  1. Enable the TLS layer on proxy listener by adding the ssl parameter to the listen directive, port 3128 is a commonly used port for forward proxies:

    nginx
    listen 10.10.1.11:3128 ssl;
#...

  2. Specify the proxy server SSL certificate and private key (the certificate that NGINX Plus presents to clients):

    nginx
    #...
ssl_certificate     /etc/ssl/certs/forward_proxy_server.crt;
ssl_certificate_key /etc/ssl/certs/forward_proxy_server.key;
#...

  3. Configure client certificate verification. Specify the trusted Client CA certificate used to validate client certificates with the ssl_client_certificate directive. With ssl_verify_client set to on, every client is required to present a valid certificate during the TLS handshake, otherwise the connection will be rejected:

    nginx
    #...
ssl_client_certificate /etc/ssl/certs/forward_proxy_client_ca.crt;

ssl_verify_client      on;
ssl_verify_depth       1;

ssl_protocols             TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers on;
#...

Conditional forward proxy access based on mTLS

Based on the result of client certificate verification, you can implement different access policies.

This scenario enables conditional access: if a client provides a valid certificate, access is granted to all resources through the proxy. If not, access is limited to particular resources or blocked.

  1. Set the ssl_verify_client directive value to optional to allow clients to connect with or without a client certificate, making conditional access possible:

    nginx
    #...
ssl_client_certificate /etc/ssl/certs/forward_proxy_client_ca.crt;
ssl_verify_client      optional;
#...

  2. Verify the status of the client certificate using the map block and the $ssl_client_verify variable. The result will be saved to the $ssl_ok variable:

    nginx
    map $ssl_client_verify $ssl_ok {
    default 0;
    SUCCESS 1;
}

    In the map block, the value of the $ssl_ok variable depends on the status of $ssl_client_verify variable. If the result of client certificate verification is “SUCCESS”, the $ssl_ok variable gets the value 1.

  3. Check the hostname the client is going to access based on the Host header of the request (the $host variable). Access will be allowed only for example.com and its subdomains. The hostnames parameter of the map directive is required to recognize hostnames and wildcards in the hostnames:

    nginx
    map $host  $allowed_host {
    hostnames;
    default       0;
    example.com   1;
    *.example.com 1;
}

  4. Define access rules by combining the results of client certificate verification ($ssl_ok) and hostname validation ($allowed_host). To allow access to all websites, the client must present a valid client certificate. If no client certificate is provided, access is restricted to example.com and its subdomains. The result is stored in the $connect_ok variable:

    nginx
    map "$ssl_ok:$allowed_host" $connect_ok {
    default 0;
    "1:0"   1;
    "1:1"   1;
    "0:1"   1;
}

  5. Restrict upstream connections to valid CONNECT requests using the tunnel_allow_upstream directive based on the result in the $connect_ok variable:

    nginx
      tunnel_allow_upstream $connect_ok;
  tunnel_pass;

Complete example

This configuration sums up the steps and enables authorization based on client certificate verification result. Clients with valid client certificates are granted full access through the proxy. Clients without a certificate are restricted to example.com and its subdomains, all other CONNECT requests are denied.

nginx
log_format http_connect  '$remote_addr [$time_local] '
                         '$request_method $host:$request_port $status '
                         '$upstream_addr $bytes_sent $upstream_connect_time '
                         '$request_time "$http_user_agent"';


map $ssl_client_verify $ssl_ok {
    default 0;
    SUCCESS 1;
}

map $host  $allowed_host {
    hostnames;
    default       0;
    example.com   1;
    *.example.com 1;
}

map "$ssl_ok:$allowed_host" $connect_ok {
    default 0;
    "1:0"   1;
    "1:1"   1;
    "0:1"   1;
}

server {
    listen 10.10.1.11:3128 ssl;

    ssl_certificate     /etc/ssl/certs/forward_proxy_server.crt;
    ssl_certificate_key /etc/ssl/certs/forward_proxy_server.key;

    ssl_client_certificate /etc/ssl/certs/forward_proxy_client_ca.crt;
    ssl_verify_client      optional;
    ssl_verify_depth       1;

    ssl_protocols             TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;

    tunnel_allow_upstream $connect_ok;
    tunnel_pass;

    access_log logs/connect_access.log http_connect;
    error_log  logs/connect_error.log;
}

The first map block checks if the client passed the mTLS verification. It sets the $ssl_ok variable to 1 if NGINX Plus successfully verified the client certificate during the TLS handshake, and to 0 otherwise.

The second map block checks if the requested host is allowlisted: if the CONNECT target hostname is example.com or any of its subdomains, the $allowed_host variable is set to 1 and to 0 otherwise.

The third map block builds the final decision variable, $connect_ok. Its result will be evaluated by the tunnel_allow_upstream directive: if it has a non-empty value, access will be granted, with restrictions above implemented. If the client cert is valid ($ssl_ok=1), access is allowed regardless of host. If the client cert is not valid ($ssl_ok=0), access is allowed only if the host is allowlisted. Otherwise access is denied (default is 0).

The ssl_verify_client directive is set to optional which allows clients to connect with or without client certificate, making conditional access possible.

Testing

  1. Test the nginx configuration for syntax validity and apply the configuration:

    nginx
    nginx -t && \
nginx -s reload

  2. Test the proxy authentication layer for requests to verify that the proxy is protected as expected under different scenarios.

    • Client certificate is not provided:

      shell
      curl -v -x https://myproxy:3128    \
           https://www.example.com \
           --proxy-cacert ./conf/tls/ca.crt

      where:

      • myproxy:3128 is the proxy address and port
      • https://www.example.com is the destination URL requested through the proxy
      • --proxy-cacert ./conf/tls/ca.crt - the CA used to verify the proxy’s server certificate.

      Expected result: requests to example.com and its subdomains succeed (for example, 301 Moved Permanently), requests to other domains are denied (for example, 502 Bad Gateway).

    • Correct client certificate is provided (the --proxy-cert and --proxy-key parameters):

      shell
      curl -v -x https://myproxy:3128    \
           https://www.example.com \
           --proxy-cert ./conf/tls/client.crt \
           --proxy-key ./conf/tls/client.key  \
           --proxy-cacert ./conf/tls/ca.crt

      For requests to all resources, the request should succeed (for example, 301 Moved Permanently).

See also

View source
Edit this page
Create a new issue