Using X.509 authentication through a load balancer configured for TLS termination

In this configuration, the load balancer provides end user authentication by validating their client certificate. However, the client certificate still needs to be sent to all the MSS systems in order to identify the incoming user.

If the load balancer is configured to terminate the TLS connection, the user's certificate can be added to an HTTP header, extracted by the session server, and then passed to MSS for authorization. In order to pass the certificate in a header, first set the header name in the HA Cloud Session Server's container.properties file:

To pass the certificate in a header

  1. Set the header name in the HA Cloud session server's container.properties file:

    x509.header.client.cert=X-SSL-Client-Cert
  2. Set the header value to the user's certificate in the load balancer configuration. For example, using a BigIP iRule:

    HTTP::header insert X-SSL-Client-Cert [URI::encode $client_cert]

    This assumes that $client_cert has been set to the user's certificate in PEM format. If the user's certificate is in DER format, use Base64 encoding:

    HTTP::header insert X-SSL-Client-Cert [b64encode $client_cert]

    Encoding the certificate ensures that the header value is one line of ASCII text. This is required for the HA Cloud session server to read the value.

    NOTE:The client certificate authentication must still take place between the load balancer and the session server. The load balancer needs to be configured to send its certificate to the session server and the load balancer’s CA must be present in the session server’s trust store.

  3. After configuring the load balancer to send its certificate to the HA Cloud session server and configuring the user’s certificate to be passed in the header, restart the session server.

Connecting with a certificate or smart card through the load balancer will result in successful authentication and authorization as the user represented by the certificate. To verify proper operation, set the session server’s log level to DEBUG and examine the sessionserver.log file for entries like these:

Attempting to extract certificate from X-SSL-Client-Cert header. 
User <DN value> has been preauthenticated from <IP address>

Additional configuration

By default, the HA Cloud session server's trust store contains the Java CA certificates. As a result, the HA Cloud session server will accept any client certificate signed by well-known CAs. In order to ensure that only the desired load balancers connect to the session server, you must remove the Java CA certificates from the trust store and ensure only the necessary certificates are installed in the trust store.

To filter the allowed client certificates by issuer DN, set the following properties in the HA Cloud session server’s container.properties file:

X509.client.cert.issuer=<DN value>
X509.client.cert.subject=<Subject DN value>
X509.client.cert.serial=<Serial number>
X509.client.cert.sha1=<SHA1 fingerprint>
X509.client.cert.sha256=<SHA256 fingerprint>

DN values must match the load balancer's certificate issuer or subject DN exactly. The serial number value should be a decimal (base 10) value. SHA1 and SHA256 fingerprint values should be entered in hexadecimal. When any of these properties are set, the incoming certificate's attributes will be checked to ensure they match the specified property values. Authorization will fail if any values do not match.