Load balancers
Load balancers are generally classified into two categories, layer 4 load balancers and layer 7 load balancers.
In both cases, the load balancer sends and receives internet traffic on HTTPS port 443, but can be configured to route traffic to and from another port on the back-end server nodes, allowing the servlet container software on the server nodes to use an unprivileged port and thus run as an unprivileged user.
If you're upgrading from an earlier release you may need to enable HTML Local Storage which negates the need to share session state between IdP instances.
Layer 4 load balancer
With a layer 4 load balancer, the connection is established between the client and the server, and TLS is not offloaded to the load balancer. This means that the browser-facing certificate configuration on port 443, and all other TLS configuration, must be done at the server, which for us is either the Java servlet container or Apache httpd.
If you are using a layer 4 load balancer with the Shibboleth IdP software then you need to enable session stickiness aka affinity aka persistence at the load balancer to ensure that once a session has been opened with a given node it remains only on that node for the first few HTTP requests. Consult the documentation for your load balancer for information.
Layer 7 load balancer
With a layer 7 load balancer, the load balancer acts as a proxy, and maintains two TCP connections, one with the client and one with the server. TLS is offloaded to the load balancer. This means that the browser-facing certificate on port 443, and all other TLS configuration, must be done at the load balancer.
As with a layer 4 load balancer, you want every session opened to remain only on the node where it was opened for the first few HTTP requests. Layer 7 load balancers have more complex mechanisms for handling this, eg. with cookies. Consult the documentation for your load balancer for information.
Handling X-Forwarded-For headers
With a Layer 7 HTTP load balancer the only IP address that appears in the logs is that of the load balancer. If the proxy sends X-Forwarded-For headers then you can use that to log the client IP addresses; add the appropriate configurations from those below after you have installed and configured your Java servlet container according to subsequent instructions (and Apache httpd if being used).
X-Forwarded-For: Jetty
in jetty.xml within the <New id="httpConfig" ..> section:
<Call name="addCustomizer">
<Arg><New class="org.eclipse.jetty.server.ForwardedRequestCustomizer"/></Arg>
</Call>
X-Forwarded-For: Tomcat
Replace __TRUSTED_IPs__ with a list of IP addresses:
in server.xml:
<Valve className="org.apache.catalina.valves.RemoteIpValve"
internalProxies="__TRUSTED_IPs__"
remoteIpHeader="x-forwarded-for"
remoteIpProxiesHeader="x-forwarded-by"
protocolHeader="x-forwarded-proto"
/>
<Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs"
prefix="localhost_access_log" suffix=".txt"
pattern="%h %l %u %t "%r" %s %b"
requestAttributesEnabled="true"
/>
X-Forwarded-For: Apache httpd
in 0-logformat.conf:
LogFormat "%{X-Forwarded-For}i %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" proxy
in port443.conf:
SetEnvIf X-Forwarded-For "^.*\..*\..*\..*" forwarded CustomLog logs/proxy_log proxy
Also see: https://httpd.apache.org/docs/2.4/mod/mod_remoteip.html#remoteiptrustedproxy
X-Forwarded-For: Shibboleth IdP
It may also be useful to add %a to the standard audit log to include the IP
in conf/audit.xml:
<util:map id="shibboleth.AuditFormattingMap">
<entry key="Shibboleth-Audit" value="%a|%ST|%T|%u|%SP|%i|%ac|%t|%attr|%n|%f|%SSO|%XX|%XA|%b|%bb|%e|%S|%SS|%s|%UA" />
</util:map>