Configure custom SSL certificate on ActiveGate

ActiveGate version 1.165 or later
Communication between OneAgents and ActiveGate takes place over an encrypted HTTPS channel. ActiveGate provides an authentication certificate to all connecting clients. While OneAgent instances may choose to ignore the validity of such a certificate, connections from browser clients (such as the RUM JavaScript tag) do check if the hostname in the certificate is correct before sending any data.

ActiveGate can serve a custom certificate instead of the default one. You need a file in PKCS#12 format that contains a private key and its corresponding certificate chain.

Server Name Indication

To use Server Name Indication, include multiple certificates and keys in a single file.

Configure a custom certificate

To configure ActiveGate to use a custom certificate:

Copy the certificate file to the ssl directory.

  • Windows: %PROGRAMDATA%\dynatrace\gateway\ssl
  • Linux: /var/lib/dynatrace/gateway/ssl
File permissions

On Linux, make sure that copied certificate file permissions include the ActiveGate user you designated to run ActiveGate. If you didn't specify a custom user during installation, use the default dtuserag user.
On Windows, services run as a local service and no file permission modification is required.

Add the following entries to the custom.properties file:

  • Windows: %PROGRAMDATA%\dynatrace\gateway\config\custom.properties
  • Linux: /var/lib/dynatrace/gateway/config/custom.properties
[com.compuware.apm.webserver]
certificate-file = certificate-file.p12
certificate-password = password
certificate-alias = friendly-name
  • The certificate password provided in the certificate-password property is obfuscated after ActiveGate restart and the obfuscated password is stored in the certificate-password-encr property.
  • If the certificate doesn't have a friendly name, you can omit the certificate-alias.

Known limitations

  • PEM file format isn't supported.
  • The password for the PKCS#12 file must be the same as the password for the key contained in this file.
    Don't use the -twopass option in the openssl pkcs12 command.
  • It's not possible to use multiple certificate files.

Managing certificates via REST API

ActiveGate version 1.167 or later

The certificates can be managed remotely via REST API. Prepare a PKCS#12 certificate file and you can upload it to the service using REST.

Authorization token

The API token is required for authorization. API tokens can be provided via HTTP headers or other means. See Dynatrace API - Tokens and authentication

API token used for the following actions must have Active Gate certificate management permission.

Upload and activate certificate

The following REST point uploads and activates the selected certificate file. Password to the file must be the same as the password to keys contained in the file, and must be provided in X-Password custom HTTP header.

curl https://localhost:9999/e/1/api/v1/certificate/cert.p12 -H"Authorization: Api-Token x8x***" -H"X-Password: pass" -T cert.p12

If the API call was successful, the HTTP response is 200 with JSON-formatted description of the content of the activated certificate file.

If the API call failed, the HTTP response is 4xx or 5xx error codes with a plain text message.

Replace active certificate

You can't replace an active certificate using this endpoint, the operation will return HTTP 403 Forbidden. To replace an active certificate, upload the certificate under a different name, then delete the old file.

Delete certificate

Deletes the selected certificate file.

curl -XDELETE https://localhost:9999/e/1/api/v1/certificate/cert.p12 -H"Authorization: Api-Token x8x***"

If the certificate was deleted successfully, the API call responds with HTTP 200 code with no content.

If the file with that name does not exist, the API call responds with HTTP 404 Not found code.

If the certificate file is currently in use, the API call responds with HTTP 403 Forbidden code.

Activate certificate

Activates an existing previously-uploaded certificate file using the specified password.

curl -XPOST https://localhost:9999/e/1/api/v1/certificate/cert.p12/activate -H"Authorization: Api-Token x8x***" -d"{\"password\":\"pass\"}"
curl -XPOST https://localhost:9999/e/1/api/v1/certificate/cert.p12/activate -H"Authorization: Api-Token x8x***" -H"X-Password: pass"

If the certificate was successfully activated, the API call responds with HTTP 200 code with JSON-formatted description of the content of the activated certificate file.

If the requested certificate file does not exist on server, the API call responds with HTTP 404 code.

If the provided password does not match, the API call responds with HTTP 400 code.

List all certificates

Returns a JSON-formatted list of all uploaded files.

curl https://localhost:9999/e/1/api/v1/certificate/list -H"Authorization: Api-Token x8x***"

If the active keystore is on the list, its entry will contain additional details.

Example response:

[
   {
      "name":"cert_demo.p12"
   
},
   {      "name":"cert.p12",
      "desc":[         {
            "alias":"local",
            "description":"Subject:CN=localhost;Valid from:Fri Feb 15 13:16:58 CET 2019;Valid to:Sat Feb 15 13:16:58 CET 2020;Serial number:71d275dd3983c3cb9382437275dd3983c3cb93dbca"
         
},
         {
            "alias":"dynatrace",
            "description":"Subject:CN=*.clients.dynatrace.org;Valid from:Thu Feb 21 10:06:03 CET 2019;Valid to:Fri Feb 21 10:06:03 CET 2020;Serial number:6dc7008ab269ecebeed03652ce08ab269ecebeeeb33"
         
}
      
]
   
},
   {
      "name":"cert_key_1.p12"
   
}
]

Describe certificate

The API call returns a JSON-formatted description of the selected file.

curl https://localhost:9999/e/1/api/v1/certificate/cert.p12/list -H"Authorization: Api-Token x8x***" -H"X-Password: pass"
curl -XPOST https://localhost:9999/e/1/api/v1/certificate/cert.p12/list -H"Authorization: Api-Token x8x***" -H"X-Password: pass"
curl -XPOST https://localhost:9999/e/1/api/v1/certificate/cert.p12/list -H"Authorization: Api-Token x8x***" -d"{\"password\":\"pass\"}"

If the requested certificate file does not exist on server, the API call responds with HTTP 404 code.

If the password doesn't match, the API call responds with HTTP 400 code.

Example response:

{   "name":"cert.p12",
   "desc":[      {
         "alias":"local",
         "description":"Subject:CN=localhost;Valid from:Fri Feb 15 13:16:58 CET 2019;Valid to:Sat Feb 15 13:16:58 CET 2020;Serial number:7137275dd398c4182437275dd3983c3cb93dbca"
      
},
      {
         "alias":"dynatrace",
         "description":"Subject:CN=*.clients.dynatrace.org;Valid from:Thu Feb 21 10:06:03 CET 2019;Valid to:Fri Feb 21 10:06:03 CET 2020;Serial number:6d2ce08ab269ecebeee7f1bd03652ce08ab269ecebeeeb33"
      
}
   
]
}

Troubleshooting

When the certificate file and password are specified, the ActiveGate tries to use the defined configuration.

  • If either the file or the password is missing, the ActiveGate will silently fall back to the default configuration. The log entry in both cases is the same.

  • If the ActiveGate tries to use the configured certificate and determines that the configuration is unusable, it will use the default SSL certificate and write the following log entry:

UTC WARNING [<1>] [CollectorImpl] Unusable custom SSL config, falling back to default.

The ActiveGate additionally logs the reason why it couldn't use the configured certificate. For example, if the alias doesn't match the file contents, the ActiveGate will write a similar line in the log file:

UTC SEVERE [<1>] [SSLEnvironment] missing configured-alias entry in keystore:/var/lib/dynatrace/gateway/config/../ssl/cert-file.p12, available aliases: available-alias,

Create a certificate file for testing

To create a self-signed PKCS#12 certificate file for testing

Generate a key and a self-signed certificate:

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -subj "/CN=localhost"

Convert the generated files to PKCS#12 format:

openssl pkcs12 -export -inkey key.pem -in cert.pem -out cert_key.p12

or, to set a friendly name, use:

openssl pkcs12 -export -inkey key.pem -in cert.pem -out cert_key.p12 -name friendly-name