The following procedure—of directly uploading an SSL certificate to an ActiveGate—is not applicable for Cluster ActiveGates. Do not attempt to configure SSL certificates directly on a Cluster ActiveGate. If you do this, the certificate will be overwritten by automatic management performed by Dynatrace. For Cluster ActiveGates, you must upload your certificates using the Cluster Management Console or the Cluster REST API v1.
Connection to ActiveGate, from OneAgents or REST API, takes place over an encrypted HTTPS channel. ActiveGate presents a self-signed authentication certificate to all connecting clients. While OneAgent instances may ignore the validity of ActiveGate certificates (depending on configuration), connections from browser clients (such as the RUM JavaScript) do verify that the hostname listed in the certificate is correct, before they send data.
ActiveGate can serve a custom certificate instead of the default one. To configure this, you need a file in PKCS#12 format that contains a private key and its corresponding certificate chain.
Depending on root CA that signed custom ActiveGate certificate, additional configuration for OneAgent may be required. See OneAgent security.
This configuration can also be applied during ActiveGate installation, by specifying installation parameters for Linux or Windows installations.
To configure ActiveGate to use a custom certificate
Copy the certificate file to the ssl directory and set correct permissions.
On Linux, make sure that permissions of the copied certificate file include the ActiveGate user you designated to run the ActiveGate service. If you didn't specify a custom user during installation, the default user is dtuserag.
On Windows, make sure that the LocalService account has permissions to access the copied certificate file.
Add the following entries to the custom.properties file in the ActiveGate configuration directory.
[com.compuware.apm.webserver]certificate-file = certificate-file.p12certificate-password = passwordcertificate-alias = friendly-name
You need to add the above entries in the [com.compuware.apm.webserver] section. If there already is such a section in your custom.properties file, then just add the properties to the section. If the section doesn't exist, then create the section heading as well.
The certificate password, which you provide in the certificate-password property, will be obfuscated, following the restart of ActiveGate main service. The obfuscated password is stored in the certificate-password-encr property, while the original property is deleted.
The value of certificate-alias must be specified in lower case. If the certificate doesn't have a friendly name, you can omit the certificate-alias property.
The certificates can be managed remotely via REST API. Prepare a PKCS#12 certificate file and you can upload it to ActiveGate using REST.
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 ActiveGate certificate management permission.
The following REST point uploads and activates the selected certificate file. The password for the file must be the same as the password for the keys contained in the file, and they must be provided in an X-Password custom HTTP header.
curl https://{address of ActiveGate}:{port}/e/{environment ID}/api/v1/certificate/{certificate file name} -H"Authorization: Api-Token {token}" -H"X-Password: {password}" -H"Content-Type: application/octet-stream" -T {path to certificate file}
The port is configurable, 9999 by default.
The path to the certificate file can be just the name of a local file, or it can be a full path.
The name of the certificate, as given in the URL, does not have to match the name of the file.
For example:
curl https://myActiveGate:9999/e/myEnvironmentId/api/v1/certificate/cert.p12 \-H "Authorization: Api-Token 123abc" \-H "X-Password: myPassword" \-H "Content-Type: application/octet-stream" \-T cert.p12
If the API call is successful, the HTTP response will be 200 with JSON-formatted description of the content of the activated certificate file.
If the API call fails, the HTTP response will be a 4xx or 5xx error code, with a plain text message.
You can't replace an active certificate using this endpoint. The operation will return HTTP 403 Forbidden. To replace an active certificate, upload a new certificate under a different name, then delete the old certificate.
Deletes the selected certificate on ActiveGate.
curl -XDELETE https://myActiveGate:9999/e/myEnvironmentId/api/v1/certificate/cert.p12 -H"Authorization: Api-Token 123abc"
If the certificate is deleted successfully, the API call will respond with HTTP 200 code with no content.
If the file with the specified name does not exist, the API call will respond with HTTP 404 Not found code.
If the certificate file is currently in use, the API call will respond with HTTP 403 Forbidden code.
Activates an existing previously-uploaded certificate file using the specified password.
curl -XPOST https://myActiveGate:9999/e/myEnvironmentId/api/v1/certificate/cert.p12/activate -H"Authorization: Api-Token 123abc" -d"{\"password\":\"pass\"}"
curl -XPOST https://myActiveGate:9999/e/myEnvironmentId/api/v1/certificate/cert.p12/activate -H"Authorization: Api-Token 123abc" -H"X-Password: pass"
If the certificate is successfully activated, the API call will respond 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 the ActiveGate, the API call will respond with HTTP 404 code.
If the provided password does not match, the API call responds with HTTP 400 code.
Returns a JSON-formatted list of all uploaded files.
curl https://myActiveGate:9999/e/myEnvironmentId/api/v1/certificate/list -H"Authorization: Api-Token 123abc"
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=myActiveGate;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"}]
Note that the default self-signed certificate is not included in the list.
This API call returns a JSON-formatted description of the selected file.
curl https://myActiveGate:9999/e/myEnvironmentId/api/v1/certificate/cert.p12/list -H"Authorization: Api-Token 123abc" -H"X-Password: pass"
curl -XPOST https://myActiveGate:9999/e/myEnvironmentId/api/v1/certificate/cert.p12/list -H"Authorization: Api-Token 123abc" -H"X-Password: pass"
curl -XPOST https://myActiveGate:9999/e/myEnvironmentId/api/v1/certificate/cert.p12/list -H"Authorization: Api-Token 123abc" -d"{\"password\":\"pass\"}"
If the requested certificate file does not exist on the ActiveGate, the API call will respond 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=myActiveGate;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"}]}
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
remembering that the friendly-name must be given in lower case.
PKCS#12 file must be the same as the password for the key contained in this file.-twopass option in the openssl pkcs12 command.