Enable SSL for the .NET Agent

This page describes how to configure the AppDynamics .NET Agent to connect to the Controller with SSL. 

Requirements

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

• Identify the Controller SSL port:
  • For SaaS Controllers, the SSL port is 443.
  • For on-premises Controllers, the SSL port is 8181 by default, but it is possible to configure on-premises Controllers to use other ports at installation.
• 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.
  • .NET Agent supports self-signed certificates when these conditions exist:
    • The Common Name (CN) on the certificate matches the URL of the Controller that the agent is calling.
    • The public key for the self-signed certificate is installed on the Windows Trusted Root Certification Authorities store where the agent is installed.

Establish Trust for the Controller's SSL Certificate

The .NET Agent requires that the Common Name (CN) on the Controller certificate matches 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 DigiCert, 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:

If an intermediate CA signed the Controller certificate, you must import the certificate for the intermediate CA in addition to the one for the root CA that signed the intermediate CA certificate. If your Controller is publicly accessible, you can use a certificate checker to identify the certificates required to complete the trust chain.

This example shows the Intermediate Certification Authorities store:

Certificate Management Tips

• 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 is not successful, then try the Third-Party Root Certification Authorities store.

Enable SSL for the .NET Agent

You can update the SSL settings for the agent by:

• Using the AppDynamics Agent Configuration Utility, or 
• Editing the settings directly in the config.xml

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

Configure SSL Using the AppDynamics Agent Configuration Utility

1. Launch the AppDynamics Agent Configuration utility.
2. In Controller Configuration, set the Port Number to the SSL port for the Controller.
   • For a SaaS Controller, set the Port Number to 443.
   • For an on-premises Controller, set the Port Number to the on-premises SSL port. The default is 8181.
3. Click Enable SSL.
   • When you enable SSL, the agent secures communication to the Controller using the protocols set for ServicePointManager.SecurityProtocol in your application.
   • By default, the configuration utility enables TLS 1.2, making it the first option in the list of secure protocols. This affects all secure communications from your application, not just requests to the AppDynamics Controller. To disable TLS 1.2, click to deselect this option.
4. Click Next and proceed with the rest of the panes to complete the configuration.
5. Restart instrumented applications: IIS applications or application pools, Windows services, and standalone applications.

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

iisreset

Upon restart, the agent connects with the Controller via SSL.

Configure SSL Using config.xml

1. Open the config.xml file as administrator. See Administer the .NET Agent. 
2. Update the following SSL settings:
   • Controller port attribute: set to the on-premises SSL port. The default is 8181. See Controller Port Attribute.
   • Controller SSL attribute: set to true. See Controller SSL Attribute. When you enable SSL, the agent secures communication to the Controller using the protocols set for ServicePointManager.SecurityProtocol in your application. 
   • Controller enable TLS 1.2 attribute: Optionally set 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 Controller.
3. Save your changes.
4. Restart the AppDynamics.Agent.Coordinator service.
5. Restart instrumented applications: IIS applications or application pools, Windows services, and 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-Premises 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>

Troubleshooting Issues

If you verified all prerequisites and still have communication issues, verify that the default ciphers are enabled in Windows Server.

Check this Registry key:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Ciphers\

If subkeys exist, your operations team may have disabled certain ciphers.