PROXY Protocol

IBM Application Gateway (IAG) supports the PROXY protocol for identifying clients.

The PROXY protocol provides a convenient way to safely transport connection information such as a client's address across multiple layers of NAT or TCP proxies. Detailed information on the proxy protocol can be found in the haproxy specification.

The PROXY protocol consists of a single header which is transmitted by the proxy to the destination before the standard network communication takes place. This is illustrated in the following diagram:

IAG has the ability to accept the proxy protocol header and then use the client address information contained within the header as the 'real' address of the client. The client address is used in the credential, request logs and auditing records. IAG can recognize the proxy protocol header for both version 1 and version 2 of the proxy protocol.

Configuring the PROXY Protocol

The PROXY protocol can be enabled for the HTTP and HTTPS endpoints by specifying the http_proxy and https_proxy protocols respectively in server/protocols.

For example:

version: 23.04
server:
  protocols:
    - http_proxy
    - https_proxy
  ...

By default, only the https protocol is enabled with support for the PROXY protocol disabled.

If PROXY protocol support is enabled for a protocol, IAG will always expect the PROXY protocol header to be supplied. If the header is not supplied an error message will be logged and the connection will be immediately closed.

Security Considerations

When using the PROXY protocol all clients which are able to communicate with IAG's front-end are assumed to be trusted. That is, a malicious client could provide a forged PROXY protocol header to provide incorrect or misleading client information.

For this reason, when using the PROXY protocol it is important to restrict the clients which can communicate with IAG to known and trusted origins within your infrastructure such as load balancers and proxies. Clients can be restricted using the server/client_ip_rules entry.

Configuring Client IP Rules

server/client_ip_rules provides a mechanism to set which clients are permitted to communicate with IAG.

The client IP address of each request is evaluated against each client IP rule in sequence until a match is found. The rule prefix (+ for accept, - for reject) is then used to determine whether the client connection should be accepted. If the client IP matches none of the configured client IP rules, the client will be accepted.

If the client is denied access the connection will be closed immediately, without any further processing. If the client is allowed access the connection request will proceed normally.

Client IP rules can contain the pattern matching characters * and ?.

For example, the following configuration allows connections from 10.0.0.2, 192.168.2.* and forbids all others (*):

version: 23.04
server:
  client_ip_rules:
    - +10.0.0.2
    - +192.168.2.*
    - -*
  ...