This site hosts historical documentation. Visit www.terracotta.org for recent product information.
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:
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.
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 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.
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:
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-truststorejavax.net.ssl.trustStoreAlternatively, 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.
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.
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.
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.
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.
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.
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.
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:
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.
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:
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>
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.
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.
The JVM running the TMS must have the same server-authentication certificate in one of the following locations:
${user.home}/.tc/mgmt/tms-truststorejavax.net.ssl.trustStoreIf a truststore was already set up for the TMS and it contains the required public key, then skip this step.
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.
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:
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 will be rejected by the TMS unless a valid certificate is found.
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.
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:
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.
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.
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.