• /
  • Log in

Configuring your SSL certificates

To communicate with the New Relic collector over HTTPS, you need to have the proper certificates for trusted signers in the trust store on your app server. By default, most JREs contain a valid root certificate that allows the agent to connect to newrelic.com.

For SSL connection issues, please visit SSL or connection errors (Java).

Notice of expired SSL certificates and certificate removal

Caution

The SSL certificates that were bundled with Java agent versions 6.1.0 to 6.4.2 have expired and are no longer valid. This means that Java agent versions 6.1.0 to 6.4.2 can no longer use the certificates bundled with the agent to establish a connection with New Relic and that you must provide your own SSL certificates.

Please see this community forum post for additional details.

Important

Java agent versions higher than 6.4.2 no longer ship with SSL certificates bundled into the agent. You must provide your own SSL truststore to the agent by explicitly using the ca_bundle_path configuration option, or by using the default truststore provided by the JDK/JRE (the agent will look to use the latter by default). Additionally the use_private_ssl configuration option has been removed from Java agent versions higher than 6.4.2.

Users wishing to add the global certificate to their local trust store can download the DigiCert Global Root CA from DigiCert.

Java Agent versions 6.2.0 - 6.4.2

Starting with Java agent version 6.2.0, the use_private_ssl configuration option has been reintroduced so you can use the SSL certificates that are bundled into the agent jar. The following bundled SSL certificates are valid for up to a year after release.

META-INF/certs/eu-newrelic-com.pem
META-INF/certs/eu01-nr-data-net.pem
META-INF/certs/newrelic-com.pem

Important

The Java agent will begin logging a warning message upon application startup when there are less than three months before the bundled certificate expires.

When the bundled certificates expire, the Java agent will no longer be able to connect to New Relic and you must either update to the latest agent version or provide a valid certificate using the ca_bundle_path configuration.

Users wishing to add the global certificate to their local trust store can download the DigiCert Global Root CA from DigiCert.

Using YAML-based configuration

common:  default_settings
  ca_bundle_path: /path/to/digicert.pem
  use_private_ssl: false

  #
  # ============================== LICENSE KEY ===============================

  # You must specify the license key associated with your New Relic
  ...

Summary

There are two configuration settings that determine what certs are used by the agent to establish a secure connection to New Relic. They are: use_private_ssl and ca_bundle_path. Here's how they work together:

  • DEFAULT: Neither configuration option (ca_bundle_path/use_private_ssl) is provided, because both are using default values. The agent will use the default SSL certificates bundled into the Java Development Kit (JDK). If these certificates aren't present or don't include certificates that trust New Relic, then the agent will not connect. You'll need to merge valid certificates into your JDK certificate bundle.
  • Only use_private_ssl is configured. The agent will use the SSL certificates that are bundled with it.
  • Only ca_bundle_path is configured. The agent will try to connect using the custom SSL certificates bundle at the configured path. If the configured custom certificate bundle doesn’t include certificates that trust New Relic, then the agent will not connect. You'll need to merge valid certificates into your custom certificate bundle.
  • Both use_private_ssl and ca_bundle_path are configured. The ca_bundle_path configuration setting takes precedence and the use_private_ssl config is ignored. This behavior is the same as only specifying ca_bundle_path.

Java Agent versions 6.0.0/6.1.0

Starting in 6.0.0, the Java agent no longer includes the nrcert global certificate chain. Users wishing to add the global certificate to their local trust store must download the DigiCert Global Root CA from DigiCert.

Note: In versions 6.1.0+, the Java agent will use a bundled New Relic certificate that is valid for up to a year after release. Before the certificate expires, you must either update the agent to the latest version or provide a valid certificate using the ca_bundle_path configuration.

Important

The Java agent will begin logging a warning message upon application startup when there are less than three months before the bundled certificate expires.

Using YAML-based configuration

common:  default_settings
  ca_bundle_path: /path/to/digicert.pem

  #
  # ============================== LICENSE KEY ===============================

  # You must specify the license key associated with your New Relic
  ...

Java Agent versions prior to 6.0.0 (Deprecated)

For Java agent versions prior to 6.0.0, applications that require valid certificates may add them in one of the following two ways:

  • Use YAML-based configuration.
  • Add the bundled list of New Relic trusted signers to the local store.

Using YAML-based configuration

The New Relic Java agent bundles the list of trusted signers in the agent newrelic.jar file. If you do not want to change the local trust store, you can activate them by setting use_private_ssl to true in the newrelic.yml agent configuration file:

common:  default_settings
  use_private_ssl: true

  #
  # ============================== LICENSE KEY ===============================

  # You must specify the license key associated with your New Relic
  ...

For more help

Additional documentation resources include New Relic for Java (compatibility and requirements, installation, and configuration.)

Create issueEdit page
Copyright © 2021 New Relic Inc.