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 |
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 authentication
If you use an mTLS-terminating reverse proxy as an added layer of security, you can configure it to URL-encode client certificate headers before passing them on to PingFederate.
Client certificate header authentication allows PingFederate to consume these URL-encoded client certificate headers.
-
Select Enable Client Certificate Header Authentication
-
In the Client Certificate Encoding list select either Apache mod_ssl or nginx.
Client certificate header name and chain header name
Apache HTTP Server with mod_ssl
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.
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:
-
In the Client Certificate Header Name field, enter
LEAF_CERT. -
In the Client Certificate Chain Header Name field, enter
CHAIN.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. |
NGINX Server
If you use mutual client certificate authentication and want to use the NGINX Server, configure the NGINX Server to pass client certificates as HTTP request headers and enter the header names.
The following examples show the NGINX Server configured to pass the client certificates as an HTTP header:
server {
...
ssl_client_certificate /etc/ssl/certs/nginx/ca-chain.cert.pem;
ssl_verify_client on;
ssl_verify_depth 2;
location / {
proxy_pass https://pingfederate:9031/;
...
# The client certificate header
proxy_set_header x-proxy-ssl-client-escaped-cert $ssl_client_escaped_cert;
...
}
...
}
To configure PingFederate to consume these HTTP request headers for mutual client certificate authentication, in the Client Certificate Header Name field, enter x-proxy-ssl-client-escaped-cert.
|
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 NGINX Server is immediately in front of your PingFederate environment. The specified values must match the header names used in the NGINX Server configuration, omitting the trailing number from the chain header names. |