Sun Java System Application Server Enterprise Edition 8.2 High Availability Administration Guide

The proxyHandler Property

The proxy handler for the Application Server is responsible for retrieving information about the original client request that was intercepted by a proxy server (in this case, a load balancer) and forwarded to the Application Server, and for making this information available to the web application (deployed on the Application Server) that is the target of the client request. If the intercepting proxy server is SSL-terminating, the proxy handler retrieves and makes available additional information about the original request, such as whether the original request was an HTTPS request, and whether SSL client authentication is enabled. Use the proxyHandler property only if authPassThroughEnabled is set to true.

The proxy handler inspects incoming requests for the custom request headers through which the proxy server conveys the information about the original client request, and makes this information available to the web application on the Application Server using standard ServletRequest APIs.

The proxy handler implementation is configurable, either globally at the HTTP service level or for individual HTTP listeners, with the proxyHandler property, whose value specifies the fully-qualified class name of an implementation of the com.sun.appserv.ProxyHandler abstract class. Configurable proxy handler implementations allow the Application Server to work with any proxy server, as long as the proxy handler implementation knows about the HTTP request header names, and understands the format of their values, through which the proxy server conveys information about the original client request.

The proxy handler for the Application Server reads and parses the SSL certificate chain from the request header. This allows a back-end application server instance to retrieve information about the original client request that was intercepted by an SSL-terminating proxy server (in this case, a load balancer). You can use the default proxy handler settings, or configure your own using the proxyHandler property of the HTTP service or HTTP/HTTPS listener. The proxyHandler property specifies the fully-qualified class name of a custom implementation of the com.sun.appserv.ProxyHandler abstract class used by the listener or all listeners.

An implementation of this abstract class inspects a given request for the custom request headers through which the proxy server communicates the information about the original client request to the Application Server instance, and returns that information to its caller. The default implementation reads the client IP address from an HTTP request header named Proxy-ip, the SSL key size from an HTTP request header named Proxy-keysize, and the SSL client certificate chain from an HTTP request header named Proxy-auth-cert. The Proxy-auth-cert value must contain the BASE-64 encoded client certificate chain without the BEGIN CERTIFICATE and END CERTIFICATE boundaries and with \n replaced with % d% a.

You can only use this property if authPassThroughEnabled is set to true. If you set the proxyHandler property on an individual HTTP or HTTPS listener, it overrides the setting default setting for all listeners.

Use the asadmin set command to set the proxyHandler property on the HTTP service or the individual HTTP listener.

To set the proxyHandler property on all HTTP/HTTPS listeners, use the following command:

asadmin set cluster-name-config.http-service.property.proxyHandler=classname

To set it on an individual listener, use the following command:

asadmin set cluster-name-config.http-service.http-listener.listener-name.property.proxyHandler=classname