X.509 Authentication

X.509 client authentication allows clients to authenticate to servers with certificates rather than with a user name and password by leveraging the X.509 public key infrastructure (PKI) standard.

MSS has additional information on X.509 configuration.

Enabling X.509 client authentication

When the user accesses the web client using TLS the browser sends a certificate to the session server identifying the end user and completing the TLS handshake.
The session server refers to its truststore to check the client’s certificate and verify its trust.
Once the TLS negotiation is complete (the session server trusts the end user), the session server sends the end user’s public certificate to MSS for further validation.
MSS also verifies that it trusts the end users certificate using its trust store.
When MSS finishes the validation, the end user will have successfully authenticated.

The client’s full certificate chain needs to be present in the session server and MSS truststores or alternatively signed by a Certificate Authority that is present in the truststores.

The browser determines what client certificate to send using a browser or smart card specific configuration.

Basic steps

Trust certificates in the session server and MSS if they have not already been trusted.
Restart the servers.
Configure X.509 in the MSS Administrative Console.

Trust the certificate in MSS and the session server

Trust the certificate in MSS

MSS’ trusted store may already contain your signing authority certificate. This is often the case with well-known certificate signing authorities, and if so, then you can skip this step.

To check:
Open the Administrative Console, click Configure Settings, and open the Trusted Certificates tab. Open Trusted Root Certificate Authorities to see a list of available certificates.
If your certificate is not listed you need to install your signing root CA into MSS following the prompts and documentation in the Administrative Console.
Trust the certificate in the session server

To install the certificate into the session server:

In <install_directory>\sessionserver\etc import the certificate:

    keytool -importcert -file <cert-file> -alias <alias-to-store-cert-under>
    -keystore trustcerts.bcfks -storetype bcfks -providername BCFIPS
    -providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider
    -providerpath ../lib/bc-fips-*.jar
    -storepass changeit

Restart all the servers

For the configuration to take effect, you must restart all servers.

Configuring X.509 with LDAP fail over in the MSS Administrative Console

Once the certificates are in place, you can enable X.509 with the Fallback to LDAP authentication option in Management and Security Server Administrative Console | Configure Settings | Authentication & Authorization. See the Administrative Console online help for descriptions of the configuration options.

Enabling X.509 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 HACloud Session Server's container.properties file:

To pass the certificate in a header

Set the header name in the HACloud session server's container.properties file:

x509.header.client.cert=X-SSL-Client-Cert
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 HACloud 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.
After configuring the load balancer to send its certificate to the HACloud 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 HACloud session server's trust store contains the Java CA certificates. As a result, the HACloud 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 HACloud 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.