This page applies to an earlier version of the AppDynamics App IQ Platform.
For documentation on the latest version, see the 4.4 Documentation.


Skip to end of metadata
Go to start of metadata

This topic covers how to configure the .NET Agent (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.

Prerequisites

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.

Enable SSL

There are two ways to update the SSL settings for the agent. You can use the AppDynamics Agent Configuration Utility. Otherwise, edit the settings directly in the config.xml, see Administer the .NET Agent

When you enable SSL for the .NET Agent, you automatically enable SSL for the .NET Machine Agent.

To configure SSL using the AppDynamics Agent Configuration utility

1. Launch the AppDynamics Agent Configuration utility.

2. In the Controller Configuration window, set the Port Number to the SSL port for the Controller.

  • For a SAAS Controller, set the Port Number to 443.
  • For an on-premise Controller, set the Port Number to the on-premise SSL port. The default is 8181.

3. Click Enable SSL.

This example demonstrates connection to an on-premise Controller listening for SSL on port 8181:

4. Click Next and proceed with the rest of the windows to complete the configuration.

5. Restart instrumented applications: IIS applications or application pools, Windows services, or standalone applications.

If you use automatic tier configuration, restart IIS. For example, open a command prompt and run:

iisreset

Upon restart the agent connects with the Controller via SSL.

To configure SSL in the config.xml

1. Open the config.xml file as administrator. See Administer the .NET Agent

2. Update the SSL settings. See Controller Element.

3. Save your changes.

4. Restart the AppDynamics.Agent.Coordinator service.

5. Restart instrumented applications: IIS applications or application pools, Windows services, or standalone applications.

If you use Automatic configuration, restart IIS. For example, open a command prompt and run:

iisreset

Upon restart the agent connects with the Controller via SSL.

Sample SaaS SSL config.xml configuration

<?xml version="1.0" encoding="utf-8"?>
<appdynamics-agent xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <controller host="mycompany.saas.appdynamics.com" port="443" ssl="true" enable_tls12="true">
    <application name="MyDotNetApplication" />
  </controller>
...
</appdynamics-agent>

Sample on-premise SSL config.xml configuration

<?xml version="1.0" encoding="utf-8"?>
<appdynamics-agent xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <controller host="mycontroller.mycompany.com" port="8181" ssl="true" enable_tls12="true">
    <application name="MyDotNetApplication" />
  </controller>
...
</appdynamics-agent>

Establish Trust for the Controller's SSL Certificate

The .NET Agent requires that the Common Name (CN) on the Controller certificate match the DNS name of the Controller. Additionally, certificates for the root CA that signed the Controller's SSL certificate must reside in the Windows Trusted Root Certification Authorities store for the Local Computer.

Certificates signed by a publicly known Certificate Authority

The root certificates for most publicly trusted CA signing authorities, such as Verisign, Thawte, and other commercial CAs, are in the Trusted Root Certification Authorities store by default.

Certificates signed by an Internal Certificate Authority

If your organization uses internal CA to sign certificates, you may need to obtain the root CA certificate from your internal security management resource. To import the root certificate, see Adding certificates to the Trusted Root Certification Authorities store for a local computer.

This example shows how to use the Certificate snap-in for the Microsoft Management Console to import a certificate for a Trusted Root Certification Authority:

(info) If an intermediate CA signed the Controller's certificate, you must import the certificate for the intermediate CA in addition to the one for the root CA that signed the intermediate CA's certificate. If your controller is publicly accessible, you can use a certificate checker to identify the certificates required to complete the trust chain. See the certificate checker from Thawte.

This examples shows the Intermediate Certification Authorities store:

Self-Signed Certificates

The App Agent for .NET does not support self-signed certificates. In order to implement SSL, the Controller must use a certificate signed by a trusted CA signing authority or an internal trusted root CA. See Security.

Troubleshooting Tips

  • By default the .NET Agent encrypts communications with the controller using TLS 1.2. If you are unwilling or unable to use TLS 1.2, set the Controller enable TLS 1.2 attribute to "false". See "Controller Element" on .NET Agent Configuration Properties.

    New in 4.0.4When you enable SSL, the agent secures communication to the Controller using the protocols set for ServicePointManager.SecurityProtocol in your application. Set the Controller enable TLS 1.2 attribute to "true" to add TLS 1.2 as the first option in the list of protocols. This affects all secure communications from your application, not just requests to the AppDynamics Controller.See "Controller Element" on .NET Agent Configuration Properties.
  • If you imported certificates for a root or intermediate CA, verify the certificate store where you imported them. Import them to Certificates (Local Computer).

  • The AppDynamics SaaS Controller uses certificates signed by DigiCert. In some cases, SaaS customers must import the DigiCert root certificates into the Windows Trusted Root Certification Authorities store.
  • In some cases system administrators set up group policies that require external certificates be imported to the Third-Party Root Certification Authorities store. If importing the certificate for the root CA to the Windows Trusted Certification Authorities store doesn't work, try the Third-Party Root Certification Authorities store.

Troubleshoot Communication Issues

If you have verified all prerequisites, but have communication issues try the following:

  •  Verify the default ciphers are enabled in Windows Server:
    Check the HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Ciphers\ registry key. If subkeys exist, your operations team may have disabled certain ciphers. Please contact support for assistance.
  • If you are installing on Windows Server 2003 and the Certificate Authority is running on Windows Server 2008, you must install a hotfix from Microsoft: https://support.microsoft.com/en-us/kb/968730 . Otherwise you may see the following error: Controller communication failed. Details: The underlying connection was closed. Could not establish trust relationship for the SSL/TLS secure channel.