Forward Proxy

In certain environments, configuring an HTTP forward proxy is necessary for Cadenza to communicate with external services or to access the internet in general. Cadenza allows the configuration of such a proxy.

When configuring a forward proxy, the following aspects should be considered:

All components and services that Cadenza should reach directly without going through the proxy must be configured as proxy exclusions. This includes, for example, the report generator, a Keycloak or other OIDC identity provider, local geo services such as the disy Geocoding Wrapper, Cadenza Analytics Extensions, and any other custom applications.
The proxy configuration applies to both HTTP and HTTPS communication. Separate proxy settings for HTTP and HTTPS are currently not supported.

Configuration Options

There are two ways to configure a forward proxy for Cadenza:

Using JVM system properties - The proxy is configured at the JVM level and applies to all applications running in the same JVM.
Using the Cadenza configuration - The proxy is configured specifically for Cadenza only.

Option 2 is particularly useful when Cadenza is deployed alongside other applications in the same Apache Tomcat (see Installation as WAR file) and the proxy configuration should only apply to Cadenza.

Option 1: JVM System Properties

To use JVM system properties for proxy configuration, enable useSystemDefaults in the Cadenza configuration. Note that "system defaults" refers to the JVM system properties, not the operating system’s proxy settings.

XML
YAML

core-config.xml configuration file

<configuration>
  <httpProxy>
    <useSystemDefaults>true</useSystemDefaults>
  </httpProxy>
</configuration>

myConfig.yaml

cadenzaconfig:
  settings:
    core:
      httpProxy:
        useSystemDefaults: true

Then configure the proxy using JVM startup parameters, for example:

-Dhttp.proxyHost=my-squid-proxy.example.com -Dhttp.proxyPort=3128 -Dhttp.nonProxyHosts=localhost|*.example.com

For a complete list of available properties, refer to the official Java Networking Properties documentation.

JVM system properties do not natively support proxy authentication with username and password. If proxy authentication is required, use option 2 instead.

Option 2: Cadenza Configuration

To configure the proxy directly in the Cadenza configuration:

XML
YAML

core-config.xml configuration file

<configuration>
  <httpProxy>
    <host>my-squid-proxy.example.com</host>
    <port>3128</port>
    <userName>proxyuser</userName>
    <password>my5tr0n9P@SS</password>
    <excludedHosts>
      <host>localhost</host>
      <host>.example.com</host>
    </excludedHosts>
    <useSystemDefaults>false</useSystemDefaults>
  </httpProxy>
</configuration>

myConfig.yaml

cadenzaconfig:
  settings:
    core:
      httpProxy:
        host: "my-squid-proxy.example.com"
        port: 3128
        userName: "proxyuser"
        password: "my5tr0n9P@SS"
        excludedHosts:
        - localhost
        - .example.com
        useSystemDefaults: false

The userName and password fields are optional and only required if the proxy requires authentication.

Setting useSystemDefaults to false (which is the default) ensures that the JVM system properties are not used and the proxy settings from the Cadenza configuration are applied.

For a full reference of all available configuration options, see core.

PDF Report Export with Forward Proxy

If you are using the PDF report export with a remote report generator (remoteWebDriverUrl), the proxy exclusions must contain the hostnames of both the remote report generator and Cadenza itself (matching the configured cadenzaUrl). The proxy settings are automatically passed to the Chromium browser of the report generator, and communication between the report generator and Cadenza must not be routed through the proxy.