TLS Mutual Authentication

Mutual authentication with TLS provides the Knox gateway with the means to establish a strong trust relationship with another party. This is especially useful when applications that act on behalf of end-users send requests to Knox.

While this feature does establish an authenticated trust relationship with the client application, it does not determine the end-user identity through this authentication. It will continue to look for credentials or tokens that represent the end-user within the request and authenticate or federate the identity accordingly.

To enable TLS Mutual Authentication, set the following in CM > Knox > Configuration > Knox Service (or Gateway) Advanced Configuration Snippet (Safety Valve) for conf/gateway-site.xml:

gateway.client.auth.needed = true

The truststore path for client authentication can be set in Clouder Manager > Knox > Configuration > Knox Service (or Gateway) Advanced Configuration Snippet (Safety Valve) for conf/gateway-site.xml

gateway.truststore.path

This parameter can point to the standard truststore (typically truststore.jks) on the host if it contains all of the necessary TrustedCertEntry's for client authentication. Even if the JKS is password protected, Knox can still get TrustedCertEntry content from it, so no password is necessary.

If gateway.client.auth.needed = true and gateway.truststore.path is unset,then it will look at this default location /var/lib/knox/gateway/data/security/keystores/gateway.jks for truststore AND keystore entries, which is an atypical configuration for JKS usage in our stack and not recommended.

These two parameters are distinct, but can point to the same truststore: gateway.truststore.path is for client authentication in the context of TLS Mutual Authentication, and gateway.httpclient.truststore.path is for when the Knox Gateway is an HTTP Client to other TLS servers.