Certificate-Based Client Authentication

About this task

As an alternative to the hash-based message authentication scheme of basic security (as described in Basic Connection Security), you can use certificate-based client authentication with BigMemory Go nodes. This form of authentication is not available for use with the Terracotta Server Array.

Setting up client authentication automatically turns off hash-based authentication. Note that you must configure SSL to use this security option. For procedures, see Adding SSL.

You must set up keystores for all managed agents and a truststore for the TMS as described in Basic Connection Security and Adding SSL. In addition, you must also set up truststores for all managed agents and a keystore for the TMS, as described in the following procedure.

To enable certificate-based client authentication:

Procedure

Enable client authentication on the REST service by setting the managementRESTService element's needClientAuth attribute to "true" in the managed agent's configuration:

<ehcache ...> 
...  
  <managementRESTService enabled="true" 
  securityServiceLocation="http://localhost:9889/tmc/api/assertIdentity" 
  sslEnabled="true" needClientAuth="true" /> 
... 
</ehcache>

Provide a truststore for the managed agent at the default location, ${user.home}/.tc/mgmt/truststore, or by setting the truststore location with the system property javax.net.ssl.trustStore.
The password for the truststore must be included in the managed agent's keychain.
The password must be keyed with the truststore file's URI. Or set the password with the system property javax.net.ssl.trustStorePassword.
Provide an identity store for the TMS at the default location, ${user.home}/.tc/mgmt/tms-keystore, or by setting the identity-store location with the system property javax.net.ssl.keyStore.
The managed agent is rejected by the TMS unless a valid certificate is found.
The password for the TMS identity store must be included in the TM keychain, as described in Creating a Shared Secret.
The password must be keyed with the identity-store file's URI. Alternatively, set the password with the system property javax.net.ssl.keyStorePassword.
To allow an SSL connection from the managed agent, an SSL connector must be configured. If the TMS is deployed with the provided Jetty web server, add the following to /management-console/etc/jetty.xml (in the BigMemory kit) as shown:
```
<Configure id="sslContextFactory" class="org.eclipse.jetty.util.ssl.SslContextFactory">
    <Set name="KeyStorePath">etc/dev-keystore.jks</Set>
    <Set name="TrustStorePath">etc/dev-keystore.jks</Set>
    <Set name="KeyStorePassword">terracotta</Set>
    <Set name="TrustStorePassword">terracotta</Set>
    <Set name="KeyManagerPassword">terracotta</Set>
    <Set name="NeedClientAuth">true</Set>
</Configure>
```
Note the following about the configuration shown:
- If the TMS WAR is deployed with a different container, make the equivalent changes appropriate to that container.
- The SSL port must be free (unused by any another process) to avoid collisions.
- maxIdletime can be set to a value that suits your environment.
- If the default keystore or truststore are not being used, enter the correct paths to the keystore and truststore being used.
- Passwords have been obfuscated using a built-in Jetty tool:
```
java -cp lib/jetty-util-9.4.11.v20180605.jar org.eclipse.jetty.util.security.Password myPassword
```
The lib folder is the /management-console/jetty-distribution/lib/ folder in your product installation. The jar file name consists of "jetty-util" followed by additional characters. If the name of your jetty-util jar file does not match the one shown above, adapt the java command accordingly.

This command returns an obfuscated version of myPassword.