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.
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 and add the following entries to the config/custom.properties
file:
[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 thecertificate-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 theopenssl pkcs12
command. - It's not possible to use multiple certificate files.
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/desk/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