Enable SSL for the Java Agent

On this page:

Related pages:

This topic covers how to secure communication between the AppDynamics Java Agent and the following AppDynamics components using SSL:

AppDynamics Controller. Before you configure the agent to communicate with the Controller via SSL, you must either use a SaaS Controller or configure the on-premises Controller to use SSL.
AppDynamics Analytics Agent. Before you configure the agent to communicate with the Analytics Agent via SSL, you must Enable SSL for the Analytics Agent.

The Java Agent supports extending and enforcing the SSL trust chain when in SSL mode.

Gather SSL Configuration Details

In preparation to secure Java Agent communications via SSL, you need information about the SSL configuration of the Controller or the Analytics Agent:

The SSL port.
- For SaaS Controllers the SSL port is 443.
- For on-premises Controllers the default SSL port is 8181, but you may configure the Controller to listen for SSL on another port.
- You configure the port for the Analytics Agent using the ad.dw.http.port property. See Enable SSL for the Analytics Agent.
The signature method for the certificates:
- A publicly known certificate authority (CA) signed the certificate. This applies for DigiCert, Verisign, Thawte, and other commercial CAs.
- A CA internal to your organization signed the certificate. Some companies maintain internal certificate authorities to manage trust and encryption within their domain.
- The Controller or Analytics agent uses a self-signed certificate.

Establish Trust for the Controller SSL Certificate

To establish trust between the Java Agent and the AppDynamics Controller, you must import the root certificate for the authority that signed the Controller's certificate into the agent truststore.

If you secured your on-premises Controller with a self-signed certificate, see Keystore Certificate Extractor Utility for instructions to create the agent truststore.

Obtain the root certificate for the authority that signed the certificate for the Controller.

Run the Java keytool command to import the root certificate. The command creates the keystore in the versioned agent configuration directory if it doesn't exist:

keytool -import -alias rootCA -file <root_certificate_file_name> -keystore <agent_home>/<version_number>/conf/cacerts.jks -storepass <truststore_password>

For example:

keytool -import -alias ControllerRootCA -file /usr/home/appdynamics/DigicertGlobalRootCA.pem -keystore /usr/local/appagent/4.3.0.0/conf/cacerts.jks -storepass MySecurePassword

Make note of the truststore password, you need it to configure the Java Agent.

Enable SSL between the Java Agent and the Controller

Configure the following system properties in the versioned controller-info.xml: <agent_home>/<version_number>/conf/controller-info.xml. See "SSL Configuration Properties" on Java Agent Configuration Properties for full details on each property:

Controller Port: the SSL port for the controller. 443 for AppDynamics SaaS.
<controller-port>443</controller-port>
Controller SSL Enabled: true.
<controller-ssl-enabled>true</controller-ssl-enabled>
Controller Keystore Password: the plain text password for the agent truststore.
<controller-keystore-password>MySecurePassword</controller-keystore-password>
If you have enabled the Secure Credential Store, encrypt the password and enter it here. See Encrypt Agent Credentials.
Controller Keystore Filename: path of the agent truststore relative to <agent home>/<version>/conf. Required if you use a truststore other than the default <agent_home>/<version_number>/conf/cacerts.jks.
<controller-keystore-filename>../../conf/cacerts.jks</controller-keystore-filename>

You can specify the Controller port and enable SSL for the Controller in the JVM startup script, but you must specify the truststore password and filename in the versioned controller-info.xml file.

Restart the JVM after you complete the configuration changes.

Sample controller-info.xml with SSL and Secure Credential Store encryption enabled

<?xml version="1.0" encoding="UTF-8"?>
<controller-info>
    <controller-host>mycompany.saas.appdynamics.com</controller-host>
    <controller-port>443</controller-port>
    <controller-ssl-enabled>true</controller-ssl-enabled>
    <!-- Encrypted Controller keystore / agent trust store password -->
    <controller-keystore-password>Tw49bd0hdCMBoQ5pfMMuYA/cA5B4pouVPkv48ovRm6c=</controller-keystore-password>
    <controller-keystore-filename>../../conf/cacerts.jks</controller-keystore-filename>
    ...
    <!-- Secure Credential Store configuration -->
    <!-- Enable the Secure Credential Store -->
    <use-encrypted-credentials>true</use-encrypted-credentials>
    <!-- Path to they secure credential keystore -->
    <credential-store-filename>/opt/appdynamics/secretKeyStore</credential-store-filename>
    <!-- Obfuscated secure credential keystore password -->
    <credential-store-password>n/8GvAZsKk4gM3Z6g+XQ1w==</credential-store-password>
</controller-info>

Establish Trust for the Analytics Agent SSL Certificate

To establish trust between the Java Agent and the Analytics Agent, you must import the root certificate for the authority that signed the Analytics Agent's certificate into the agent truststore.

Obtain the root certificate for the authority that signed the certificate for the Analytics Agent.

Run the Java keytool command to import the root certificate into the JRE truststore.

keytool -import -trustcacerts -alias analytics-agent -file <root_certificate_file_name> -keystore <agent_home>/<version_number>/conf/cacerts.jks

For example:

keytool -import -trustcacerts -alias analytics-agent -file /usr/home/appdynamics/MyAnalyticsCert.crt -keystore /usr/local/appagent/4.3.0.0/conf/cacerts.jks

Enable SSL between the Java Agent and the Analytics Agent

To enable the Java Agent to access the Analytics Agent over SSL, configure the appdynamics.analytics.agent.url system property for the JVM:

Use the HTTPS protocol.
Use the Analytics Agent SSL port. The port should be the same value as the Analytics Agent ad.dw.http.port property. See Enable SSL for the Analytics Agent.

-Dappdynamics.analytics.agent.url=https://<analytics_agent_host>:<analytics_agent_port>/v2/sinks/bt

For example:

java -javaagent:/home/appdynamics/agent/javaagent.jar -Dappdynamics.controller.hostName=mycontroller.example.com -Dappdynamics.controller.port=8090 -Dappdynamics.analytics.agent.url=https://my.analytics.host.example.com:9090/v2/sinks/bt -Dappdynamics.agent.applicationName=ACMEOnline -Dappdynamics.agent.tierName=Inventory -Dappdynamics.agent.nodeName=Inventory1 ACMEOnline.jar

Restart the JVM after you complete the configuration changes.

Secure the Java Agent Truststore

Take the following security measures to prevent tampering with the Java Agent truststore:

Secure the truststore file through filesystem permissions:
- Make the agent truststore readable by any user.
- Make the truststore owned by a privileged user.
- Make the truststore writable only by the specified privileged user.
Secure the agent configuration files so that they are only readable by the agent runtime user and only writable by a privileged user:
- Versioned configuration file: <agent_home>/<version_number>/conf/controller-info.xml.
- Global configuration file: <agent_home>/conf/controller-info.xml.

Keystore Certificate Extractor Utility

The Keystore Certificate Extractor Utility exports certificates from the Controller's Java keystore and writes them to an agent truststore. It installs to the following location:

<agent_home>/<version_number>/utils/keystorereader/kr.jar

To avoid copying the Controller keystore to an agent machine, you can run this utility from the Controller server. Access the agent distribution on the Controller at the following location:

<controller_home>/appserver/glassfish/domains/domain1/appagent

Execute kr.jar and pass the following parameters:
- The full path to the Controller's keystore:
```
<controller_home>/appserver/glassfish/domains/domain1/config/keystore.jks
```
- The truststore output file name. By default the Java Agent looks for cacerts.jks.
- The password for the Controller's certificate, which defaults to "changeit". If you don't include a password, the extractor applies the password "changeit" to the output truststore.
```
/<full path to application JRE>/bin/java -jar kr.jar <controller_home>/appserver/glassfish/domains/domain1/config/keystore.jks cacerts.jks <controller_certificate_password>
```
Install the agent trust store to the versioned agent configuration directory:
```
<agent_home>/<version_number>/conf/
```

Resolve SSL Issues

If you run into problems with the version of TLS/SSL, see "SSL Compatibility between Java Agent and Controller" on Agent and Controller Compatibility and "AppDynamics Agent SSL Protocol Property" on Java Agent Configuration Properties.