.NET Agent SSL Support

When a .NET Agent establishes a secure (SSL) connection with a Controller, the .NET Agent uses a default mechanism embedded in the .NET framework to verify a Controller (server) certificate which relies on the local Trust Store. As a result, the Controller certificate must be signed by one of the publicly trusted authorities.

Therefore, if the Controller uses:

  • a self-signed certificate, or
  • a certificate signed by a custom authority

Then the SSL connection cannot be established until:

  • a self-signed certificate, or
  • a custom authority are manually added to the local Trust Store.
Note: If a Controller uses a certificate signed by a publicly trusted authority, then no extra set up is required.

If you do not want to manually add a certificate to the local Trust Store, you can configure the .NET Agent to consume the Controller custom trusted certificate and establish a secured connection automatically.

Limitations

Custom trusted certificate validation is supported with these noted limitations for the .NET runtimes:

  • .NET Core >= 2.0
  • .NET Framework >= 4.7.2
  • .NET Standard >= 2.1
Note: You may use applications that were complied using earlier .NET versions as long as the .NET runtime is later than or equal to the listed limitations.

If you reach a runtime limitation, then you can either:

  • Upgrade the .NET runtime to a supported version, or
  • Add a Controller custom certificate to the local Trust Store, disable the feature, and then continue using the SSL connection to a Controller based on the default validation mechanism.

Supported Configurations

You can configure the Controller Custom Trusted Certificates by providing either a:

  • Path to one certificate file: A file may contain one, or multiple valid certificates, in one of these formats:
    • Base-64 Encoded X.509 (.cer)
    • DER Encoded Binary X.509 (.cer)
    • PKCS 7 (.p7b)
    • PKCS 12 (.pfx)

Or

  • Folder containing multiple certificate files: A folder may contain several files with one or multiple certificates inside; and the folder may contain subfolders. There is no limitation on the structure except that all files in the folder must contain valid certificates; if one file is not a valid certificate, then all of them are ignored.

Select only one of these configurations. If you configure both a certificate file and a certificate folder, then a warning displays alerting you that only the certificate file will be used in the configuration.

Note: You are not required to provide a private key in your certificate files; only a public key is required. Splunk AppDynamics does not expose any sensitive information from the provided certificates. Use caution when providing files to an outside source.

Standalone Windows Agent Configuration

Configure the config.json file:

JSON 
{
	"controller": {
		"certfile": "C:\certs\certificate.crt",
		"certdir": "C:\certs\",
	}
}

Environment Variables Used for Standalone Windows Agent

Using the command line, set these environment variables to override the config.json file:

CODE 
APPDYNAMICS_CONTROLLER_SSL_CERTFILE=C:\certs\certificate.crt
APPDYNAMICS_CONTROLLER_SSL_CERTDIR=C:\certs\

Agent MSI Agent Configuration

Configure the config.json file without overriding the environment variables:

CODE 
<appdynamics-agent xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <controller ssl-certificate-file = "C:\certs\certificate.crt" ssl-certificate-directory = "C:\certs\" >
    ...
  </controller>
  ...
</appdynamics-agent>

Parity Difference with Linux .NET Agent <=20.11.x

These are the existing parity differences with Linux .NET Agent <= 20.11.x:

  • Certificate files formats are extended.
  • Multiple certificates are supported in files.
  • There is no name constraint for the files.
  • There is no constraint on the folder structure.
  • Full framework is supported.
  • You are not required to provide a full chain of the Controller certificates. You can configure the .NET Agent trust using an end leaf certificate, or just a custom authority certificate, or both; whichever is convenient.