This site hosts historical documentation. Visit www.terracotta.org for recent product information.

Commercial Products
Open Source

Terracotta Management Console Security Setup

Introduction

The Terracotta Management Console (TMC) includes a flexible, multi-level security architecture to integrate with a wide variety of contexts.

The following levels of security are available:

  • No authentication, and no or limited secured connections. The non-enterprise version of the TMC is restricted to this mode, while enterprise versions can run in this mode by choice.
  • Default role-based user authentication only. This is built in and set up when you first connect to an enterprise version of the TMC.
  • Basic security offering authentication and authorization of clients (managed agents), as well as message hashing and other protective measures.
  • Secured connections based on Secure Sockets Layer (SSL) technology, which includes certificate-based server authentication, can be used in conjunction with basic security.
  • Certificate-based client authentication to enhance SSL-based security. In this case, no message hashing is used.

With the exception of certificate-based client authentication and message hashing, these different 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 an enterprise version of the TMC.

This document discusses security from the perspective of the TMC. However, the TMC and the Terracotta Management Server (TMS) function in the same security context, and by extension the security measures discussed here also apply to the TMS.

No Security

Upon initial connection to an enterprise version of the 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. Note that with authentication disabled, the TMC cannot connect to secured nodes.

If you are running the non-enterprise version of the TMC, no security features are available. You can, however, 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. Note that connections between the TMC and managed agents such as Ehcache clients, remain unsecured. 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.

Set up the role-based accounts using the account setup page, which appears when you first connect to the TMC with authentication enabled, or after you enable authentication in the TMC Settings dialog. You can set up two role-based accounts:

  • Administrator – This account has read-write control over all aspects of the TMC, including accounts and connections.
  • Operator – This read-only account can view statistics and other information about configured connections. This account cannot add or edit accounts or connections.

After you enter a username and password for each account, click Setup. You will be logged out, and can now log in using the credentials you have set up.

Basic Connection Security

You can secure the connections between the TMS and managed agents using a built-in hash-based message authentication scheme. This level of security authenticates managed agents (providing client-server authentication without need of certificates) and ensures that communication between the TMS and managed agents is secure. 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.

To use basic security, follow these steps:

  1. Have a Terracotta trial or full license file in the Terracotta root installation directory.

  2. Use the EE version of the agent (ehcache-ee-rest-agent-<version>.jar).

  3. Enable security (authentication via identity assertion) 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 location of the TMC installation, with /tmc/api/assertIdentity appended as in the example above.

  4. Create a shared secret for the assertion of trust between the TMC and any security-enabled instances of the Ehcache REST service you wish it to connect to.

    Using a command line, run the following script located in the TMC bin directory:

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

    where <url> is the URL of the agent. This value should correspond exactly to the URL you use within 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 prompt you for 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.

  5. If you will use the TMC to manage more than one agent, run the add-tc-agent script once for each agent, using that agent's URL. The script saves these entries to the file <user_home>/.tc/mgmt/keychain. Do not move or delete this file—it must remain accessible to the TMC at that location.

  6. Each agent with a keychain entry must also have a local copy of the keychain file saved to the same directory:

    <user_home>/.tc/mgmt/keychain

    To create separate keychain files for each agent, see Creating Individual Keychain Files.

Creating Individual Keychain Files

You may need to create additional keychain files for managed agents, if they run on different machines from the TMS. If you run the application with the agent on the same machine as the agent (for example, the local host), then you don't need to make an additional keychain file. The one you created for the TMS is sufficient.

To create an individual keychain file for a managed agent, use the keychain script provided in the kit's tmc/bin directory:

bin/keychain.sh -O -S -c /path/to/myKeychainFile http://myHost:9889/

where myKeychainFile is the name of the keychain file to create, and http://myHost:9889/ is the URI associated with the managed agent. This is the same URI configured in the TMC to connect to the managed agent. Use keychain.bat with Microsoft Windows.

The "/path/to/myKeychainFile" should be a temporary location on the machine running this script. (If it is on the machine with the TMS, be careful not to overwrite the keychain file that you created for the TMS.) On the machine running the agent, copy the keychain file to the directory:

<user_home>/.tc/mgmt/keychain

When you run the keychain script, the following prompt should appear:

Terracotta Management Console - Keychain Client
KeyChain file successfully created in /path/to/myKeychainFile
Open the keychain by entering its master key:

Enter the master key, then answer the prompts for the secret to be associated with the managed agent:

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

Note the acknowledgment upon successful generation of the keychain file. However, the script does not enforce the matching of the secret that you associate with the URI— this string-URI combination must match the one stored in the keychain file with the TMC.

Adding SSL

In an environment where connections may be intercepted, or a higher level of authentication is required, adding SSL provides encryption and certificate-based server authentication. SSL can be used to enhance basic security.

To add SSL, follow these steps:

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

    <ehcache ...>
...  
  <managementRESTService enabled="true" 
securityServiceLocation="http://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 TMC must have the same server-authentication certificate in one of the following locations:

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

  5. If a custom truststore (not cacerts) is designated for the TMC, the truststore password must be included in the TMC 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

You can configure certificate-based client authentication environments where you are required to use that standard or simply to use the type of authentication and encryption offered by certificates. Configuring this option for managed agents disables hash-based message authentication, a basic security feature that is unneeded with certificate-based client authentication. Note that you must configure SSL to use this security option.

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. The following example is for Ehcache:

    <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 TMC is deployed with the provided Jetty web server, add the following to tmc/etc/jetty.xml 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 (via HTTPS port 9443).

To force all web browsers to connect using SSL, disable the non-secure connector by commenting out that connector in tmc/etc/jetty.xml:

<!-- 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 (tmc/etc/jetty.xml) uses a JKS identity store saved at the root directory (tmc). 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.

Visit www.terracotta.org for most recent product information.