PingFederate Server

Configuring incoming proxy settings

Use the options in the Incoming Proxy Settings window to let PingFederate access the information it needs to construct correct responses for incoming requests.

When PingFederate is deployed behind an application load balancer (ALB), a network load balancer (NLB), a reverse proxy, or a similar network traffic management solution on-premises or in the cloud, the following options enable PingFederate to use information in HTTP headers added by the reverse proxy to construct correct responses. These options, configurable on Security → System Integration → Incoming Proxy Settings, apply globally to all incoming requests.

HTTP header for client IP addresses

The HTTP Header for Client IP Addresses field allows you to globally specify the header name (for example, X-Forwarded-For) where PingFederate should attempt to retrieve the client IP address in all HTTP requests sent to PingFederate. Defining this field helps PingFederate identify the correct client IP address when PingFederate is operating behind a load balancer or something similar.

By design, the X-Forwarded-For header exposes privacy-sensitive information, such as the IP address of the client. This header is untrustworthy when no trusted reverse proxy exists between the client and server. PingFederate assumes that a trusted proxy verifies any headers configured in the Incoming Proxy Settings rather than coming directly from the client. Therefore, we recommend that customers only configure headers in Incoming Proxy Settings that are proxied through a trusted source.

Load balancers and proxies commonly append the IP address from an incoming request to the X-Forwarded-For (or similar) header. If you enter X-Forwarded-For as the value of the HTTP Header for Client IP Addresses field, PingFederate combines multiple comma-separated header values in the same order that they are received. Define which IP address you want to use in the list box:

  • Leave the default of Use Last Value to use the last value in the combined list.

  • Select Use First Value to use the first value in the combined list.

HTTP header for hostname

The HTTP Header for Hostname field allows you to globally specify the header name (for example, X-Forwarded-Host) where PingFederate should attempt to retrieve the hostname and port in all HTTP requests sent to PingFederate. Proxies commonly append the hostname and port from an incoming request to the X-Forwarded-Host (or similar) header. If you enter X-Forwarded-Host as the value of the HTTP Header for Hostname field, PingFederate combines multiple comma-separated header values into the same order that they are received. Define which hostname you want to use in the list box:

  • Leave the default of Use Last Value to use the last value in the combined list.

  • Select Use First Value to use the first value in the combined list.

Client certificate header name and chain header name

If you use mutual client certificate authentication and want to use the Apache HTTP Server with mod_ssl as the incoming proxy, configure the Apache HTTP Server to pass client certificates as HTTP request headers and enter the header names on the Incoming Proxy Settings window.

The following examples shows the Apache HTTP Server configured to pass the client leaf certificate and up to four intermediate certificates as headers.

...
SSLOptions +ExportCertData
RequestHeader set LEAF_CERT "%{SSL_CLIENT_CERT}s"
RequestHeader set CHAIN0    "%{SSL_CLIENT_CERT_CHAIN_0}s"
RequestHeader set CHAIN1    "%{SSL_CLIENT_CERT_CHAIN_1}s"
RequestHeader set CHAIN2    "%{SSL_CLIENT_CERT_CHAIN_2}s"
RequestHeader set CHAIN3    "%{SSL_CLIENT_CERT_CHAIN_3}s"
...

This configuration snippet is for demonstration purposes only.

To configure PingFederate to consume these HTTP request headers for the purpose of mutual client certificate authentication:

  • Enter LEAF_CERT as the Client Certificate Header Name.

  • Enter CHAIN as the Client Certificate Chain Header Name.

    Do not enter the trailing number from the chain header names.

Because HTTP request headers could potentially be forged, you should only specify a Client Certificate Header Name and a Client Certificate Chain Header Name if the Apache HTTP Server is immediately in front of your PingFederate environment. The specified values must match the header names used in the Apache HTTP Server configuration, omitting the trailing number from the chain header names.

Incoming proxy terminates HTTPS connections

The Incoming proxy terminates HTTPS connections option allows you to globally specify that connections to the reverse proxy are made over HTTPS even when HTTP is used between the reverse proxy and PingFederate.