There can be situations where it is necessary to add additional certificates to the certificate store shipped with ActiveGate. Follow the procedure described below to add an additional certificate to an existing ActiveGate.
If you prefer, additional trusted root certificates can also be specified during ActiveGate installation, by specifying installation parameters for Linux or Windows.
ActiveGate connects to other Dynatrace components (clusters, servers) or third-party systems (such as VMware, Cloud Foundry, Kubernetes or OpenShift) using SSL-secured channels. The root CA certificate store shipped with ActiveGate (the default certificate set shipped with Java) is sometimes insufficient to cover all the required use cases.
For example:
If such situations occur, an error in the ActiveGate log file will state that a certificate presented by a server to which your ActiveGate was trying to connect was not trusted. In these cases, you need to import the missing certificate to the ActiveGate.
Adding a certificate is a potential security concern. Consult your organization's security compliance team before adding a new trusted root certificate to ActiveGate to be sure that your organization's security will not be compromised by your actions. If an error is reported in the ActiveGate log stating that a certificate presented by a server, to which your ActiveGate was trying to connect, was not trusted, do not assume that you need to add a missing certificate. Further research is required before proceeding.
An invalid certificate error can also mean that there has been an attempt to breach the security of your organization. You should, therefore always investigate this possibility, when such an error is reported.
If you want to configure truststore certificates for extensions, see Oracle Database monitoring configuration.
To upload the certificate for custom Extensions verification, see Upload your root certificate.
Before you add a certificate to the ActiveGate, you need to obtain it and place it in the ca.crt file.
Obtaining the CA certificate is highly context-specific and there are no simple steps to follow. Consult appropriate sources in your organization to obtain the required certificates.
For details, see the General information about CA certificates section below.
ActiveGate version 1.333+
You can use agctl to configure trusted root certificates.
agctl trust-store set --certificates=/path/to/ca.crt
agctl trust-store set --certificates=/path/to/ca.crt --truststore=custom-truststore.p12 --password=mypassword
--certificates: Path to the certificate file(s) in PEM format (required)--truststore: File name for the truststore in the ActiveGate SSL directory (optional, default: mytruststore.p12)--password: Password for the truststore (optional, default: changeit)After configuring the trust store with agctl, you must restart ActiveGate for the changes to take effect.
Section: [collector]
| Property | Default value | Description |
|---|---|---|
trustedstore | unset | Your trusted keystore (optional). The property trustedstore should contain the path to the file holding trusted certificates. That path should be relative to the ActiveGate SSL directory. Please also see Trusted root certificates for ActiveGate. |
trustedstore-exclusive | unset | When set to true, ActiveGate will no longer merge the built-in trust store (shipped with JRE) with the custom trust store defined by you in trustedstore. The custom trust store will be the only trust store used for communication. |
trustedstore-password | changeit | Password of your trusted keystore (optional) which is encrypted during ActiveGate start. The obfuscated password is then stored in trustedstore-password-encr. |
trustedstore-type | pkcs12 | Java default format of key and certificate databases (optional). |
ActiveGate logs its actions related to the above configuration. The configured truststore will not be used (and the truststore configuration will be left unchanged) if any of the following is true:
javax.net.ssl.trustStore system property is specified.ssl/runtime.cacerts file.The following general information about CA certificates may help you to determine the required certificates:
To create a trusted SSL connection for your certificate authority, the following conditions must be met:
To see which certificates the endpoint is presenting you can use the following command:
openssl s_client -connect <API_ENDPOINT>:<PORT> -showcerts -servername <API_ENDPOINT_HOSTNAME>
Some applications (for example OpenShift) can present different certificates depending on the SNI. ActiveGates will set the configured endpoint hostname in the SNI.
If the above command presents a full certificate chain then you must add the root certificate to the ActiveGate truststore. You can add the intermediates as well, but they are not necessary if the API endpoint presents them.
If the above command does not present a full certificate chain, then the root of the chain must be obtained elsewhere.
For example, the endpoint of the openssl request to this server—see below—only returns the server certificate, and not the root certificate.
You know that this server only presents a server certificate and not a root certificate because the error says unable to get local issuer certificate. If the root certificate were present, the error message would say "Self-signed certificate in certificate chain".
To create a valid SSL connection to this endpoint, you must obtain the root certificate separately.
openssl s_client -connect localhost:6443CONNECTED(00000005)depth=0 CN = kube-apiserververify error:num=20:unable to get local issuer certificateverify return:1depth=0 CN = kube-apiserververify error:num=21:unable to verify the first certificateverify return:1---Certificate chain0 s:CN = apiserveri:CN = DynatraceRootAuth---Server certificate-----BEGIN CERTIFICATE-----MDIDYGCCAkigAwIBAgJIJ8SQ/FcmJiYwDQZJKoZIhvcNAQESBQAwFTETMBEGA1UEAxMKa3ViZXJuZXRlczAeFw0yMTAxMjcxOTM1MDhaFw0yMjAxMjcxOTM1MDhaMBkxFzAVBgNVBAMTDmt1YmUtYXBpc2VydmVyMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKSAQEA15BVGULXSXZAM6a4Y7lR6JfSBOXIAq1sCoydH2AdhzqHu0mXj+FdsooRQ46f7bySZvMGFfLupmaAzH5kVJOVDQ2WoHPYVzAEhDji+SUBOi99AC0tevEaONLdkLGzR//2u8XND0iiswsGkK3yaNyPwCVnOnA3c4O32waMoM1VI9XGuNSqqfQF6XUx8sGHG5bNVzfHOXh5CBJZ5JReDhW/J8CbPElYJPJaQcSpTVFx5ReTQqBLeBSyeWyCwqMj/jAnKzpPffO478If/Uc8I5vS8zi2yPhYJhKqD0m1b96hH0slXKho25Ipgpu4cIw03mQZMK558W4d6ccww/OvMbpKQQIDAQABo4GvMIGsMA4GA1UdDwEB/wQEAwIFoDATBgNVHSUEDDAKBgfrBgEFBQcDATSBhAYDVR0RBH0we4IPamstazhzLWNsb25lLTAwggprdWJlcm5ldGVzghJrdWJlcm5ldGVzLmRlZmF1bHSCFmt1YmVybmV0ZXMuZGVmYXVsdC5zdmOCAGt1YmVybmV0ZXMuZGVmYXVsdC5zdmMuY2x1c3Rlci5sb2NhbIcECmAAAYcErBcSvDANBgkqhkiG9w0BAQsFAAOCAQEAdmOq/Sp74xiLCa14EI/9v7jUG+GqjD3HPpj/oXIdLHg6HA4nixxcxwnWAf2RAMVXBYn7qTDU6x7W5M+t6M0uaCe8Od8oKjOKeQ31dfMpPbLYprKmcnuBriiN5gjfghINZKaZlGlX0GkBC9TsTHYbmWfXfvfsX2xfpc4J0esfK+BafllEimCx8blnw1uY7CiCedEANePT+J5Q+m9Lm5pu7Qz/B4JDHLIJBArhFTBM6IIF6DhoqGUXM1XXqMlTVBpxz2vhf0N/HxcTaEBaVWu7GZbk5mCYhngmRJ8PJ3uA8yajDT2muWm/la5oOI/GeuTgR98tqjXOXmz2NjvEZng1CA==-----END CERTIFICATE-----subject=CN = kube-apiserverissuer=CN = kubernetes---Acceptable client certificate CA namesCN = kubernetes
The certificate below is an example root certificate for the above server certificate. Make sure that you only add root certificates that you trust, to your truststores.
For example:
cat ca.crt | openssl x509 -text -nooutCertificate:Data:Version: 3 (0x2)Serial Number: 0 (0x0)Signature Algorithm: sha256WithRSAEncryptionIssuer: CN = kubernetesValidityNot Before: Jan 27 19:35:08 2021 GMTNot After : Jan 25 19:35:08 2031 GMTSubject: CN = kubernetesSubject Public Key Info:
You can see that this is the root certificate you need because the subject and issuer are identical, and they match the issuer of the server certificate shown above ('kube-apiserver ').