This site hosts historical documentation. Visit www.terracotta.org for recent product information.
Note: For a brief overview of Terracotta security with links to individual topics, see Security Overview.
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.
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 or without authentication.
Authentication can also be enabled or disabled in the TMC Settings panel. 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 username and 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 Rich Internet Applications (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, that user is unable to see the Administration panel in the TMC or perform administrative tasks, such as shutting down a server. However, if a cluster is not secured, a non-Administrator user can 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, see 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 might be exposed to unwanted connection attempts from rogue agents, or where managed agents might 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), 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 already exist):
keytool -import -alias myAgent -file myAgentCert.cert \
-keystore truststore.jks
If a managed agent does not have a keystore, set one up. For examples, see the cluster security documentation.
Make your truststore available to the TMS in one of the following 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 by 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 it, 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/management-console/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 automatically creates the Terracotta keychain file <user_home>/.tc/mgmt/keychain if it does not already exist. Do not move or delete this keychain file because it must remain accessible to the TMS at that location.
When prompted, enter a shared secret of your choice.
Be sure to remember the secret that you enter because you might 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 through 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 /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 might 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. Alternatively, 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, 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. Alternatively, 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:
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 TMS keychain.
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:
<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.
Directory URL: The complete URL of the LDAP server. The URL has the format protocol://hostname:portnumber where the protocol is LDAP for standard connections or LDAPS for secure connections.
The host is the host name or IP address of the LDAP server.
The port is the port on which the server is running. The port is optional. If omitted, the port defaults to 389 for LDAP, or 636 for LDAPS. For example, specifying the URL ldaps://ldapserv1:700 would create a secure connection to the LDAP server running on the nonstandard port 700 on the host called ldapserv1.
Enter your directory system username: The user ID the TMC should supply to connect to the LDAP server, for example, “Directory manager”. This user must have permission to query groups and group membership.
Note: If your LDAP server allows anonymous access, leave this field blank. If your LDAP does not allow anonymous access, the username must map to a password in the TMC keychain, which can be configured such as:
bin/keychain.sh -O ~/.tc/mgmt/keychain ldap://admin@localhost:1389
If you want to use a LDAP URL to define a set of rules for explicit group names, consider the following configuration.
| Prompt | Example Value |
|---|---|
| Enter your directory URL | ldap://vminrwa04:1389 |
| Directory System user name | tmcoperatoruser3 |
| Search base+B41 | dc=localdomain,dc=com |
| UserDN Template | uid={0}, ou=Users, dc=localdomain,dc=com |
| Group DN Template | cn={0}, ou=Groups, dc=localdomain,dc=com |
| Is your LDAP instance working against dynamic groups? | No |
| Enter the attribute matching the user with the group | uniqueMember |
| Admin Groups, Operator group | tmcadminstgroup1,tmcadminstgroup2,tmcadminstgroup3,tmcopstgroup1,tmcopstgroup2 tmcopstgroup3,tmcadminstgroup1,tmcadminstgroup2,tmcadminstgroup3 |
| Operator group | OP,AD |
| Keychain Formation command | keychain -O -c |
| Keychain password | manageAD12 |
If you want to use a LDAP URL to define a set of rules that match only for group members, use the dynamic group feature. This alternative to explicit group names works with the filter values you provide. All the members of a dynamic group share a common attribute or set of attributes that are defined in the memberURL filter.
For example, suppose that your organization has two departments Admin and Operator. If the ldap attribute ‘departmentNumber’ for members of Admin department is AD, and the equivalent for the Operator department is ‘OP’, configure as follows.
| Prompt | Example Value |
|---|---|
| Enter your directory URL | ldap://vminrwa04:1389 |
| Directory System user name | tmcoperatoruser3 |
| Search base+B41 | dc=localdomain,dc=com |
| UserDN Template | uid={0}, ou=Users, dc=localdomain,dc=com |
| Group DN Template | cn={0}, ou=Groups, dc=localdomain,dc=com |
| Is your LDAP instance working against dynamic groups? | Yes |
| Enter the attribute matching the user with the group | departmentNumber |
| Admin Groups | AD |
| Operator group | OP,AD |
| Keychain Formation command | keychain -O -c |
| Keychain password | manageAD12 |
If you want to use a Active Directory URL to define a set of rules for explicit group names, consider the following configuration example.
| Prompt | Example Value |
|---|---|
| Enter your directory URL | ldap://10.60.29.212:389 |
| Directory System user name | tmcoperatoruser3 |
| Search base+B41 | DC=igomega,DC=com |
| Admin Groups | tmcadminstgroup1,tmcadminstgroup2,tmcadminstgroup3 |
| Operator group | tmcopstgroup1,tmcopstgroup2,tmcopstgroup3,tmcadminstgroup1,tmcadminstgroup2,tmcadminstgroup3 |
| Keychain Formation | keychain -O -c |
| Keychain password | manageAD12 |