This site hosts historical documentation. Visit www.terracotta.org for recent product information.
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:
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.
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 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 log into the TMC using the temporary initial login credentials. You can set up two role-based accounts:
After you enter a username and password for each account, click Setup. You will be logged out, and the initial login credentials can no longer be used. Users can now log in using the credentials you have set up.
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:
Have a Terracotta trial or full license file in the Terracotta root installation directory.
Use the EE version of the agent (ehcache-ee-rest-agent-<version>.jar
).
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.
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.
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.
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.
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.
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:
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>
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 TMC must have the same server-authentication certificate in one of the following locations:
${user.home}/.tc/mgmt/tms-truststore
javax.net.ssl.trustStore
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
.
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:
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>
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 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:
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 (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.
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.