Mutual TLS is a mutual authentication method that encrypts the traffic between the client and the server by authenticating each other using their public-private key pair. 

In AppDynamics Controller, you can enable Mutual TLS to authenticate the Controller with third-party applications such as Slack, PagerDuty, and ServiceNow. This mutual authentication verifies that the alerts (HTTP request actions) sent to the third-party applications are from AppDynamics and not from a malicious entity.

Configuring mutual TLS authentication involves the following steps:

  1. Generate a Certificate Signing Request (CSR) for your TLS certificate
  2. Get the CSR signed from a Certificate Authority and upload the signed TLS certificate
  3. Enable mutual TLS authentication in HTTP request actions

By default, the Mutual TLS Configuration feature is only available in the AppDynamics Controller Tenant UI with the Account Owner role. You can also create a custom role and enable this feature. For more information about the roles, see Manage Custom Roles.

Generate a Certificate Signing Request

To configure mutual TLS authentication, you need to first generate a certificate signing request (CSR) to get your TLS certificate:

  1. In the AppDynamics Controller Tenant UI, click Alert & Respond > Mutual TLS Configuration.
  2. Click + New Certificate Signing Request (CSR).
  3. Enter the following details:
    1. Organization (Optional). The legal name of your organization.
    2. Department (Optional). The name of your department handling the certificate.
    3. Country. Select the country where your organization is located. By default, the country selected is the United States. Note that this field is mandatory and can’t be left blank.
    4. State (Optional). The name of the state where your organization is located.
    5. City (Optional). The name of the city where your organization is located.
  4. Click Generate CSR. 
  5. Click Download CSR to download the .csr file. Note that you can also copy the content and save as a .csr file.

When you generate a CSR, AppDynamics creates a public- private key pair. The public key is available with the CSR and the private key resides with AppDynamics in a secure key store.

Sign the CSR and Upload the Signed TLS Certificate

After downloading the CSR file, you must get it signed from a certificate authority (CA) of your choice. You can then upload the signed TLS certificate. AppDynamics Controller also supports certificate chain. A certificate chain consists of a leaf certificate and intermediate certificates.

The intermediate certificate must be created by using the .ext file provided by your certificate authority.

To upload the signed TLS certificate on your AppDynamics Controller:

  1. Click Upload New Client Certificate.

  2. Upload the signed TLS certificate (.pem file) directly or copy and upload the Base64 encoded text from the TLS certificate.

    If you have a certificate chain, upload only the leaf and intermediate certificates as a single .pem file. Or copy and upload the Base64 encoded text of the the leaf and intermediate certificates. Do not upload the root certificate.

The following sample illustrates a certificate chain that consists of a leaf certificate and an intermediate certificate:

Certificate chain sample

-----BEGIN CERTIFICATE-----
MIIEGTCCAgGgAwIBAgIJAL5ibUhpLjFHMA0GCSqGSIb3DQEBCwUAMB0xCzAJBgNV
BAYTAklOMQ4wDAYDVQQDDAVJTlRFUjAeFw0yMzAzMjExMDMyMDdaFw0yNDAzMjAx
MDMyMDdaMFIxCTAHBgNVBAcTADEJMAcGA1UECBMAMQswCQYDVQQGEwJJTjEJMAcG
A1UECxMAMQkwBwYDVQQKEwAxFzAVBgNVBAMTDmxvY2FsaG9zdDo4MDgwMIIBIjAN
BgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAweI7PCWPgGn0o2pN3vHuqaxfKFMD
aR1HuluhVxyUaWP4FHZXnW796Qmebpmt6YSmCTjrTVtt/M5Nds+39PDuj62F8duC
g/owQtN75MHdOTLm0c9x1r6o62pjmLPLlMJmCu28agI6uKJXYMXmz8CzKJaiBz/f
j4JZyVd/Yn9GPXD7Exhul3aJX75Un7DvQBATQYfBo6BmqQz3PfeFkag6p94MjBlY
x+qAL8KeamAwtYm2Qcp3QygU6I1KsDqFsd+UvaclrRRxaY4glfjxXUldZl9Ryk/P
JAiSSaZ54uSbD9qwbcLPop2EzOcLKbR7WcZsy+k9R54x/GRXsVBP35lruQIDAQAB
oycwJTAOBgNVHQ8BAf8EBAMCBJAwEwYDVR0lBAwwCgYIKwYBBQUHAwIwDQYJKoZI
hvcNAQELBQADggIBABGlU4RGHCLzPvsxz+QMImQ6qNuN0CbetIaMhh+aaWnGVXNe
f2W1xfzo+xOvFhHMcgJJmOrkawJQmXlBF/0nDOFuW5AjKabB0pMkGdRsfLuCY3Bq
b8VYWh7K0XGwpk6kRmtGppWXVW0W3i6aHwyKiTuFRxDq3WWlzBeozkd1rbyrL0bL
kvGS6uRkWzuzNNULM5pd+qbTV32SPHPzHxJijQwbIJeenkDHmazg9v7eJHUZFuyY
rh77+2DgG4t7hwhaEhdFz4PFZ34NowWI9TzQ3y2L/xMHog2jSrz9xsG0YwhmXNY0
CYj9eMRAbDzsGkzOsB6doN0R6+TnXlbxs6HqEXHf1MVCRKG405lS+qdO8Si6ZvEN
ccNSktSOnHGIXWbYL8zPxbhAbdOQGqMwnZCOXnUjtXMg0mAE0Dr7RijS587m0PkX
1Xh1LyU3xXtwd26v+i9Srh1kwmcJpItlKPcVMtdYRILVz0jGpd/J2CDcRuvHtzB1
vHFqiUni9IWYYBhRsWZTFnh5qO1+yc9tWgx0k7fVPc4haslwTa9K6SDtBkfl7WGt
RoW8nGXBmTA4rn8Zdow14C8c/zkaZCb6/6qUZFIq//Stnu+gJEjxG7tO6JFfTp/j
/NvwyXpozI8FnKyFBTVTVCBDKPceI7Z7xRq7e95ARBT2dApXXisPmLW5bDP3
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIDzzCCAregAwIBAgIJALqp1BzVxWxiMA0GCSqGSIb3DQEBCwUAMBwxCzAJBgNV
BAYTAklOMQ0wCwYDVQQDDARyb290MB4XDTIzMDMyMTEwMjgxOVoXDTI0MDMyMDEw
MjgxOVowHTELMAkGA1UEBhMCSU4xDjAMBgNVBAMMBUlOVEVSMIICIjANBgkqhkiG
9w0BAQEFAAOCAg8AMIICCgKCAgEA0JZ/KXP4WyfYxLya5rMxTSVmHCVuWJeSYfsS
VoxOHGpksIE54Tv/g0fAjEgKbb/k6+dIwzVH5odKS/bkaQdc13HAPsSsGi0rl/ax
jK+iqhbBEXFqmyvF7hmBuA83j93dQCPTj7lYUcQxS7Kf6lh6hs+UFSLLDRBtI1ey
YbPnOljQ3jll0OdgH2MoeVXeKr/9+o2xtcXf1JfBVhMK0j8RRkNUfMn3lJJ8pUgu
6/ARfwA1esPYg4dNXUFT6CNtM8zqZuTMGdBND0yVXPagQ/KKJzBevrSvl5PIlLEV
nvwHEJtnc9sKUpK9SepAzvWdLAWhvsnaECo7tXosqF+tBHdv6J/XxhdYEjFngIz3
dJ3cqbXwzOtfEaGbCoNKsYsHiw92L/wFRE9RZIiLqBZIEOHzXXNi98s54jDU1YDR
A1Lc02Ie39vpvwiypfXEEUiuQOjbY8m4lcTiP+sahljFO3o9qoouoX4SV3YM3nSp
y1U+sSZB3mh8UCgPoPKoPl7e5JGPguMCO0NBR4hFeqREDYlcmg+50ZHaj6qUx7MD
hBi9B0p3w+fhgbyHdo0rDs75xja6M08PdHUs8Gu6D2+KLp5oyE1OaYGjcHwsdzlE
5+SJuUUD73s26JLlhDJ7EY/09pyVwnrx2PbWoeF3Tc5qX1mqBlk+1LImF6AQTb+c
1MSym3ECAwEAAaMTMBEwDwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQsFAAOC
AQEAbIWhRxGN0KIQNwpn48FAXgiKeUWuNmPb+MqlifO0u/ko5Vh8xXQmUsrGCupI
W/lhRJSsAXI4B5Ss680pne55QLOY+6dXINnsObP5Xlz6PErugfYFIxddM8OEjn06
Qn/UhehtgBQlUbv34KSrdh1ylXIGLpS3YqeGWufTlMx1WJToVfnBbF6+QIiWjTSC
pt5nkHMph/oQcqTXJoxyzY6qwPx5+fYNuNDKvIJeWbR/NX/ukR/mMTb0kEFZfbaQ
OslSWnFEk15Wk6tZzMkiZlOqf/8qjYbwr5QgXVFUHCw4F5bQKdJIelMlzQrUrOxA
3GeUYyRbfeaE4l9De4geSrphAw==
-----END CERTIFICATE-----


Points to consider:

Before uploading a new TLS certificate, ensure the following points are met:

  • The certificate must be either in the .pem or .crt format.
  • The certificate encoding scheme must be Base64.
  • The certificate must have a valid expiry date.
  • The certificate must be a client certificate.
  • The certificate must match with the corresponding CSR.
  • For a certificate chain,:
    • all the certificates must be uploaded by using a single .pem file. 
    • the first certificate must be the leaf certificate and the subsequent certificates must be the intermediate certificates. Each certificate must be signed by the subsequent certificate.
    • the leaf certificate must be a client certificate.
    • the leaf certificate must have a valid expiry date.
    • the leaf certificate must match the corresponding CSR.
    • the length of the certificate chain must not be greater than the length specified in the flag appdynamics.controller.alerting.mtls.max.certificate.chain.length. See Controller Setting for Certificate Chain Length.

If you face any error while uploading the signed TLS certificate, refer Troubleshoot Mutual TLS Certificate Issues.

View the TLS Certificate

Click Alert & Respond > Mutual TLS Configuration to view the uploaded TLS certificate. You can also click Download Certificate to download the .pem file.

If you have generated a CSR that is not yet used, you can view and download the unused CSR.

Enable Mutual TLS in HTTP Request Actions

After uploading the TLS certificate, you can enable the mutual TLS authentication for HTTP request actions. AppDynamics fetches the TLS certificate and attaches it with the HTTP request actions (alerts). On third-party endpoints that are configured to receive alerts from AppDynamics, the certificate helps to verify that the alerts are from AppDynamics.

To enable the mutual TLS authentication:

  1. Click Alert & Respond > HTTP Request Templates.
  2. Do one of the following:

  3. In the Authentication section, select the Also Turn on Mutual TLS option.

    This option is enabled only if you have uploaded a TLS certificate.

  4. Click Save.

Controller Setting for Certificate Chain Length 

The Cisco Accounts team can specify the maximum length of the certificate chain.

To change the length of the certificate chain:

  1. Log in to the Controller administration console using the root user password.

    http://<controller host>:<port>/controller/admin.jsp

  2. Select Controller Settings.
  3. Locate the flag appdynamics.controller.alerting.mtls.max.certificate.chain.length and update its value. The default value is 2.
  4. Click Save.