Call us: +1-415-738-4000

Terracotta Management Console Security Setup

Introduction

The Terracotta Management Server (TMS) includes a flexible, multi-level security architecture to easily integrate into a variety of environments.

The following levels of security are available:

  • No authentication, and no or limited secured connections. Note that if the TMS cannot locate a Terracotta license at startup, or locates a Terracotta license that does not specifically enable it, no security setup page appears and the TMS runs without security of any type.
  • Default role-based user authentication only. This is built in and set up when you first connect to TMS, and is intended to control access to the TMS. Standard LDAP and Microsoft Active Directory integration is also available.
  • Basic security offering authentication and authorization of BigMemroy Go and BigMemory Max nodes (referred to as agents or managed agents in this context), as well as message hashing and other protective measures.
  • Secured connections based on Secure Sockets Layer (SSL) technology can be used in conjunction with basic security.
  • Certificate-based client authentication to enhance SSL-based security. In this case, basic security is disabled.

With the noted exceptions, these security layers can be used together to provide the overall level of security required by your environment. Except as noted below, security features are available only with a properly licensed version of the TMS.

This document discusses security from the perspective of the TMS. However, the TMS and the Terracotta Management Console (TMC) function in the same security context.

No Security

Upon initial connection to a properly licensed TMC, the authentication setup page appears, where you can choose to run the TMC with authentication or without.

Authentication can also be enabled/disabled in the TMC Settings panel once the TMC is running. If you enable authentication, all of the security features described in this document are available.

If you do not enable authentication, you will be directly connected to the TMC without being prompted for a login/password.

Even with no security enabled, however, you can still force SSL connections between browsers and the TMC.

Default Security

Default security consists of the built-in role-based accounts that are used to log into the TMC. This level of security controls access to the TMC only, and is appropriate for environments where all components, including the TMC, managed agents, and any custom RIAs, are on protected networks. An internal network behind a firewall, where all access is trusted, is one example of such an environment. Note that connections between the TMC and managed agents remain unsecured.

Optionally, integration with an LDAP or Microsft Active Directory is also available. For more information, see the TMC help.

When TMS/TMC authentication is configured (whether with the .ini file, or LDAP or Active Directory), if a non-Administrator user logs into the TMS/TMC, he will not be able to see the Administration panel in the TMC, nor will he be able to perform administrative tasks such as shutting down a server. However, if a cluster is not secured, a non-Administrator user will be able to use the TMS Rest API to perform administrative tasks on the cluster.

In other words, if you secure the TMS/TMC but do not secure your TSA cluster, any user can perform administrative tasks on the cluster through the Rest API. To prevent this, you must secure both the TMS/TMC and your cluster.

If you are unsure whether your cluster is secured, go to the Connections tab in the Settings window, and look for the locked padlock icon next to your connection.

For more information about TSA security, refer to Securing Terracotta Clusters.

Basic Connection Security

You can secure the connections between the TMS and managed agents using a built-in hash-based message authentication scheme and digital certificates, also known as "identity assertion" (IA). Use this level of security in environments where the TMS may be exposed to unwanted connection attempts from rogue agents, or managed agents may come under attack from a rogue TMS.

NOTE: To fully secure connections between the TMS and managed agents, it is recommended that SSL be used for encryption.

To set up IA, complete the following steps:

Setting Up a Truststore

The TMS must have a truststore containing the public-key certificate of every agent that connects to it. If you are not using a Certificate Authority (which provides the public keys), you must export public keys from the self-signed certificates in the keystore of each agent using a command similar to the following:

keytool -export -alias myAgent -keystore keystore-file.jks \
    -file myAgentCert.cert

Then import the keys into the TMS truststore, creating it as shown if it does not exist:

keytool -import -alias myAgent -file myAgentCert.cert \
    -keystore truststore.jks

Note that if a managed agent does not have a keystore, you must set one up. See the cluster security documentation for examples.

Once you create a truststore for storing these public keys, it must be available to the TMS in one of the follwoing ways:

  • ${user.home}/.tc/mgmt/tms-truststore
  • a location configured with the system property javax.net.ssl.trustStore

Alternatively, you can import these public keys into the default truststore for the JVM (typically the cacerts file).

NOTE: If a different default location for TMS-related files is required, set it using the system property com.tc.management.config.directory.

Configuring IA

To configure IA for the TSA, see the TSA security setup page.

To configure IA on a Terracotta client, enable security (authentication via IA) on the REST service by adding the "securityServiceLocation" attribute to the managementRESTService element in the managed agent's configuration. The following example is for Ehcache:

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

If securityServiceLocation is not set, the authentication feature is disabled. To enable, set its value to the URI used to connect to the TMC, with /tmc/api/assertIdentity appended. In the example example above, "http://localhost:9889" is the TMC URI.

For BigMemory Go, use the same procedure as for a Terracotta client.

Creating a Shared Secret

You must create a password (or secret) that is shared between the TMS and managed agents, storing it in a Terracotta keychain file.

The scripts required in the following procedures are found in ${BIGMEMORY_GO_HOME}/management-console/bin or ${BIGMEMORY_MAX_HOME}/tools/security/bin. Use the equivalent .bat scripts for Microsoft Windows.

Shared Secret on the TMS

  1. Create a shared secret for the assertion of trust between the TMS and managed agents by running the following script:

    ./add-tc-agent.sh <agent-url>
    

    where <agent-url> is the URI of the agent. This value should correspond exactly to the URI you use in the TMC to connect to the given agent. For example:

    ./add-tc-agent.sh http://localhost:9888
    

    Use add-tc-agent.bat with Microsoft Windows.

    The script will automatically create the Terracotta keychain file <user_home>/.tc/mgmt/keychain if it does not already exist. Do not move or delete this keychain file—it must remain accessible to the TMS at that location.

  2. When prompted, enter a shared secret of your choice.
    Be sure to note the secret that you enter, as you may need to enter it again in a later step.

  3. Run the add-tc-agent script once for each agent, using that agent's URI.
    The script saves these entries to the same keychain file.

Shared Secret on Managed Agents

  1. Each agent with a keychain entry must also have access to the same shared secret via a Terracotta keychain file:

    ./keychain.sh -c <user_home>/.tc/mgmt/agentKeychainFile \ 
        http://myHost:9889/tc-management-api
    

    where <tmc-url> is the URI used to connect to the TMC, with with /tc-management-api appended. If the named keychain file already exists on the node, omit the -c flag. Agents running on the same node can share a keychain file.

  2. Enter the master key for the keychain file:

    Terracotta Management Console - Keychain Client
    KeyChain file successfully created in /path/to/agentKeychainFile
    Open the keychain by entering its master key: 
    
  3. Enter the shared secret associated with the TMS:

    Enter the password you wish to associate with this URL: 
    Password for http://myHost:9889/ successfully stored
    

    The secret you enter must match the one entered for the TMS. Note that the script's success acknowledgment does not confirm that the secret matches the one stored on the TMS.

Adding SSL

In an environment where connections may be intercepted, or a higher level of authentication is required, adding SSL provides encryption. SSL should be used to enhance basic security.

To add SSL to BigMemory Max, see the TSA security setup page.

To add SSL to BigMemory Go, follow these steps for each node:

  1. Enable SSL on the REST service by setting the managementRESTService element's "sslEnabled" attribute to "true" in the managed agent's configuration:

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

  2. Provide an identity store for the managed agent either at the default location, ${user.home}/.tc/mgmt/keystore, or by setting the store's location with the system property javax.net.ssl.keyStore.

    The identity store is where the server-authentication certificate is stored. If the identity store cannot be found, the managed agent fails at startup.

  3. Add a password for the managed agent's identity store to its keychain.

    The password must be keyed with the identity-store file's URI. Or set the password with the system property javax.net.ssl.keyStorePassword. If no password is found, the managed agent fails at startup.

  4. The JVM running the TMS must have the same server-authentication certificate in one of the following locations:

    • the default truststore for the JVM (typically the cacerts file)
    • ${user.home}/.tc/mgmt/tms-truststore
    • a location configured with the system property javax.net.ssl.trustStore

    If a truststore was already set up for the TMS and it contains the required public key, then skip this step.

  5. If a custom truststore (not cacerts) is designated for the TMS, the truststore password must be included in the TMS keychain.

    The password must be keyed with the truststore file's URI. Or set the password with the system property javax.net.ssl.trustStorePassword.

Certificate-Based Client Authentication

As an alternative to the hash-based message authentication scheme of basic 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.

You must set up keystores for all managed agents and a truststore for the TMS as described in the basic security and SSL sections. 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, follow these steps:

  1. 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>
    
  2. 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.

  3. 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.

  4. 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 will be rejected by the TMS unless a valid certificate is found.

  5. The password for the TMS identity store must be included in the TMS keychain.

    The password must be keyed with the identity-store file's URI. Or set the password with the system property javax.net.ssl.keyStorePassword.

  6. 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:

    <Call name="addConnector">
     <Arg>
       <New class="org.eclipse.jetty.server.ssl.SslSelectChannelConnector">
         <Arg>
           <New class="org.eclipse.jetty.http.ssl.SslContextFactory">
             <Set name="keyStore">/home/.tc/mgmt/tms-keystore</Set>
             <Set name="keyStorePassword">
         OBF:1v9u1w1c1ym51xmq1rwd1rwh1xmk1ym91w261v8s</Set>
             <Set name="keyManagerPassword">
         OBF:1v9u1w1c1ym51xmq1rwd1rwh1xmk1ym91w261v8s</Set>
             <Set name="TrustStore">/home/.tc/mgmt/tms-truststore</Set>
             <Set name="keyStorePassword">
         OBF:1v9u1w1c1ym51xmq1rwd1rwh1xmk1ym91w261v8s</Set>
             <Set name="needClientAuth">true</Set>
           </New>
         </Arg>
         <Set name="port">9999</Set>
         <Set name="maxIdleTime">30000</Set>
       </New>
     </Arg>
    </Call>
    

    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-runner.jar org.eclipse.jetty.util.security.Password myPassword

    This command, which must be run from the TMC root directory, returns an obfuscated version of myPassword.

Forcing SSL connections For TMC Clients

If the TMC is deployed with the provided Jetty web server, web browsers connecting to the TMC can use an unsecured connection (via HTTP port 9889). A secure SSL-based connection is also available using HTTPS port 9443.

To force all web browsers to connect using SSL, disable the non-secure connector by commenting it out in /management-console/etc/jetty.xml (located in the BigMemory kit):

<!-- DISABLED non-secure connector 
<Call name="addConnector">
  <Arg>
    <New class="org.eclipse.jetty.server.nio.SelectChannelConnector">
      <Set name="host"><Property name="jetty.host" /></Set>
      <Set name="port"><Property name="jetty.port" default="9889"/></Set>
      <Set name="forwarded">true</Set>
      <Set name="maxIdleTime">300000</Set>
      <Set name="Acceptors">2</Set>
      <Set name="statsOn">false</Set>
      <Set name="confidentialPort">8443</Set>
      <Set name="lowResourcesConnections">20000</Set>
      <Set name="lowResourcesMaxIdleTime">5000</Set>
    </New>
  </Arg>
</Call>
-->

If the TMC WAR is deployed with a different container, make the equivalent changes appropriate to that container.

About the Default Keystore

By default, the built-in Jetty container's configuration file (management-console/etc/jetty.xml) uses a JKS identity store, located in the same directory. This keystore contains a self-signed certificate (not signed by a certificate authority). If you intend to use this "untrusted" certificate, all SSL browser connections must recognize this certificate and register it as an exception for future connections. This is usually done at the time the browser first connects to the TMS.