Using the HAProxy PROXY protocol

When LDAP clients communicate through a software load balancer that supports the PROXY protocol, you can forward that client information from the software load balancer to the backend destination server.

The PingDirectory, PingDirectoryProxy, and PingDataSync servers only support the PROXY protocol for inbound LDAP connections using either PROXY header version 1 or 2.

The servers don’t support using the PROXY protocol with outbound LDAP connections or other communication protocols, such as HTTP or JMX.

Considerations and limitations

To enable PROXY protocol support for a server, you must create and configure a PROXY-dedicated LDAP connection handler. Here’s why:

An individual LDAP connection handler doesn’t support both PROXY and non-PROXY protocol connections.
The server CLI tools, the admin console, and server-to-server communication don’t support the PROXY protocol. They require at least one LDAP connection handler that isn’t configured for PROXY protocol support.
To help prevent the loss of access to administrative functions, given the previous limitations, the following restrictions apply when enabling PROXY protocol support:
- You can only enable PROXY protocol support for an LDAP connection handler when you create it.
- You can’t enable or disable PROXY protocol support for an existing LDAP connection handler.
- The LDAP connection handlers created during setup aren’t configured with support for the PROXY protocol.

Using the PROXY protocol with TLS

You shouldn’t configure the software load balancer as a TLS endpoint for LDAPS clients. Instead, you should pass the encrypted traffic through to the PingDirectory, PingDirectoryProxy, or PingDataSync server. This ensures the following:

The communication from the client to the server remains end-to-end encrypted.
The server can validate any presented client certificate chain.
The server can use the certificate chain to authenticate the client by using the SASL EXTERNAL mechanism.

Using the PROXY protocol with PingDirectoryProxy

If you put the software load balancer in front of a PingDirectoryProxy server, you can use the PROXY protocol for communication between the end client and the PingDirectoryProxy server. The PingDirectoryProxy server then uses the intermediate client control to convey the end client address, which was included in the PROXY protocol header, to the backend PingDirectory server.

Enabling PROXY protocol support

Steps

To enable support for requests forwarded through a software load balancer that uses the PROXY protocol:

Create a dedicated LDAP connection handler and set use-haproxy-proxy-protocol to true.

Example:

The following commands provide examples for creating LDAP and LDAPS connection handlers with support for the PROXY protocol, listening on ports 2389 and 2636, respectively:

$ bin/dsconfig create-connection-handler \
  --handler-name "LDAP Connection Handler With PROXY Protocol" \
  --type ldap \
  --set enabled:true \
  --set listen-port:2389 \
  --set allow-start-tls:true \
  --set ssl-cert-nickname:server-cert \
  --set key-manager-provider:JKS \
  --set trust-manager-provider:JKS \
  --set use-haproxy-proxy-protocol:true

$ bin/dsconfig create-connection-handler \
  --handler-name "LDAPS Connection Handler With PROXY Protocol" \
  --type ldap \
  --set enabled:true \
  --set listen-port:2636 \
  --set use-ssl:true \
  --set ssl-cert-nickname:server-cert \
  --set key-manager-provider:JKS \
  --set trust-manager-provider:JKS \
  --set use-haproxy-proxy-protocol:true