This topic covers how to configure the App Agent for Java (the agent) to connect to the Controller using SSL. It assumes that you use a SaaS Controller or have configured the on-premise Controller to use SSL.

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

Before You Begin

Before you configure the agent to enable SSL, gather the following information:

Identify if the Controller is SaaS or on-premise.
Identify the Controller SSL port.
- For SaaS Controllers the SSL port is 443.
- For on-premise Controllers the default SSL port is 8181, but you may configure the Controller to listen for SSL on another port.
Identify the signature method for the Controller's SSL certificate:
- A publicly known certificate authority (CA) signed the certificate. This applies for 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 uses a self-signed certificate.
Decide how to manage the configurations. See Where to Configure App Agent Properties:
- Add the configuration parameters to <agent install directory>/conf/controller-info.xml.
  Or
- Include system properties in the -javaagent argument in your JVM startup script.

SSL Utilities

We provide two utilities to help you implement SSL.

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 install directory>/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 install directory>/appserver/glassfish/domains/domain1/appagent

To use the Keystore Certificate Extractor, execute kr.jar and pass the following parameters:

The full path to the Controller's keystore:

<controller install directory>/appserver/glassfish/domains/domain1/config/keystore.jks

The truststore output file name. By default the 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.

java -jar kr.jar <controller install directory>/appserver/glassfish/domains/domain1/config/keystore.jks cacerts.jks <controller certificate password>

Password Encryption Utility

The Password Encryption Utility encrypts the Controller's certificate password so you can add it to the controller-info.xml file. It installs to the following location:

<agent install directory>/utils/encryptor/encrypt.jar

To use the Password Encryption Utility, execute encrypt.jar and pass the clear text password as a parameter. The utility returns the encrypted password:

java -jar <agent install directory>/utils/encryptor/encrypt.jar <controller certificate password>

Encrypted password is nkV/LwhLMLFjfNTbh0DLow==

SaaS Controller

1. Update the JVM startup script or controller-info.xml to use SSL enabled settings. See App Agent for Java Configuration Properties.

Set the Controller Port Property to 443. See Controller Port Property.
Set the Controller SSL Enabled Property to true. See Controller SSL Enabled Property.

2. Save your changes.

3. Restart the JVM.

The agent detects SaaS implementations based upon the controller host URL, which must contain ".saas.appdynamics.com". It also checks for an account-name and an access-key. If all three elements exist, the agent connects with the SaaS Controller via SSL.

Sample SaaS SSL controller.xml configuration

<?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>
...
	<account-name>mycompany</account-name>

	<account-access-key>xxxxxxxxxxxxx</account-access-key>
...
</controller-info>

Sample SaaS SSL JVM startup script configuration

java -javaagent:/home/appdynamics/AppServerAgent/ -Dappdynamics.controller.hostName=<controller domain> -Dappdynamics.controller.port=443  -Dappdynamics.controller.ssl.enabled=true ... -Dappdynamics.agent.accountName=<account name> -Dappdynamics.agent.accountAccessKey=<access key>

On-Premise Controller with a Trusted CA Signed Certificate

1. Update your JVM startup script or controller-info.xml to use SSL enabled settings. See App Agent for Java Configuration Properties.

Set the Controller Port Property to the on-premise SSL port. See Controller Port Property.
Set the Controller SSL Enabled Property to true. See Controller SSL Enabled Property.
To configure the agent to perform full validation of the Controller certificate, set the Force Default SSL Certificate Validation app agent node property to true. See Force Default SSL Certificate Validation Property.

2. Save your changes.

3. Restart the JVM.

The agent connects to the Controller over SSL. Because the Force Default SSL Certificate Validation app agent node roperty is set to true, the agent enforces the trust chain using the default Java truststore.

Sample on-premise SSL controller.xml configuration for a CA signed certificate

<?xml version="1.0" encoding="UTF-8"?>
<controller-info>

	<controller-host>mycontroller.mycompany.com</controller-host>

	<controller-port>8181</controller-port>

	<controller-ssl-enabled>true</controller-ssl-enabled>
 
    <force-default-certificate-validation>true</force-default-certificate-validation>

...
</controller-info>

Sample on-premise SSL JVM startup script configuration for a CA signed certificate

java -javaagent:/home/appdynamics/AppServerAgent/ -Dappdynamics.controller.hostName=<controller domain> -Dappdynamics.controller.port=443  -Dappdynamics.controller.ssl.enabled=true -Dappdynamics.force.default.ssl.certificate.validation=true ...

On-Premise Controller with an Internally Signed Certificate

1. Obtain the root CA certificate from your internal resource. By default the agent looks for a Java truststore named cacerts.jks.

To import a certificate to a truststore, run the following command:

keytool -import -alias rootCA -file <certificate file name> -keystore cacerts.jks -storepass <truststore password>

This command creates the truststore cacerts.jks if it does not exist and assigns it the password you specify.

2. Copy the truststore file to the agent configuration directory:

cp cacerts.jks <agent install directory>/conf/cacerts.jks

3. Encrypt the truststore password. See Password Encryption Utility.

4. Update your JVM startup script or controller-info.xml to use SSL enabled settings. See App Agent for Java Configuration Properties.

Set the Controller Port Property to the on-premise SSL port. See Controller Port Property.
Set the Controller SSL Enabled Property to true. See Controller SSL Enabled Property.
Set the Controller Keystore Password Property to the encrypted password. See Controller Keystore Password Property.
You must configure this property in the controller-info.xml. It is not available as a system property in the JVM startup script.

5. Restart the JVM.

The agent detects the cacerts.jks truststore in its configuration directory and uses it to enforce the trust chain when connecting to the Controller over SSL.

Sample on-premise SSL controller.xml configuration for an internally signed certificate

<?xml version="1.0" encoding="UTF-8"?>
<controller-info>

	<controller-host>mycontroller.mycompany.com</controller-host>

	<controller-port>8181</controller-port>

	<controller-ssl-enabled>true</controller-ssl-enabled>

	<controller-keystore-password>nkV/LwhLMLFjfNTbh0DLow==</controller-keystore-password>

...
</controller-info>

Sample on-premise SSL JVM startup script configuration for an internally signed certificate

java -javaagent:/home/appdynamics/AppServerAgent/ -Dappdynamics.controller.hostName=<controller domain> -Dappdynamics.controller.port=443  -Dappdynamics.controller.ssl.enabled=true ...

On-Premise Controller with a Self-Signed Certificate

1. Extract the Controller's self-signed Certificate to a truststore named cacerts.jks. See Keystore Certificate Extractor Utility.