---
url: /howto/connecting-via-https-proxy.md
---

# How to Connect Via an HTTP(S) Proxy

Sometimes, connections to external systems (source code repositories, issue trackers, etc.) have to go
through an HTTP(S) proxy and Teamscale needs to be configured appropriately.

:::tip Using an HTTP(S) Proxy with Your Cloud Instance
If your cloud instance needs to connect through an HTTP(S) proxy, please contact the Teamscale support team at <support@teamscale.com> for assistance.
:::

\[\[toc]]

## Configuring the Proxy Host and Port

At a minimum, you will need to configure the proxy's host name or IP address and its port using Java's [standard system properties][jre-proxies].
To do so, add the following to the `JVM_EXTRA_ARGS` entry in the file `$TEAMSCALE_HOME/config/jvm.properties` for HTTP and HTTPS connections, respectively:

```properties
-Dhttp.proxyHost=<HTTP-Proxy-Host>
-Dhttp.proxyPort=<HTTP-Proxy-Port>
```

```properties
-Dhttps.proxyHost=<HTTPS-Proxy-Host>
-Dhttps.proxyPort=<HTTPS-Proxy-Port>
```

Furthermore, for the HTTPS proxy, you will need to ensure that the proxy's SSL/TLS certificate can be validated using [Teamscale's certificate store](../connecting-via-https/).

## Providing Credentials to the Proxy

Sometimes, a proxy will itself require user name and password, distinct from any credentials required by the external systems accessed via the proxy.
To configure user name and password, add the following to the `JVM_EXTRA_ARGS` entry in the file `$TEAMSCALE_HOME/config/jvm.properties` for HTTP and HTTPS, respectively:

```properties
-Dhttp.proxyUser=<HTTP-Proxy-User-Name>
-Dhttp.proxyPassword=<HTTP-Proxy-User-Password>
```

```properties
-Dhttps.proxyUser=<HTTPS-Proxy-User-Name>
-Dhttps.proxyPassword=<HTTPS-Proxy-User-Password>
```

:::warning Basic Authentication Over HTTPS Proxy Tunnels
Since JDK 8u111, the JDK disables `Basic` authentication for HTTPS proxy tunnels by default as a mitigation for [CVE-2016-5597](https://nvd.nist.gov/vuln/detail/CVE-2016-5597).
If your proxy requires `Basic` authentication, also add the following to `JVM_EXTRA_ARGS` to clear the default block list so that the JVM will send `Basic` credentials on `CONNECT` requests:

```properties
-Djdk.http.auth.tunneling.disabledSchemes=
```

:::

## Bypassing the Proxy

Sometimes, only some connections to external systems should go through the HTTP or HTTPS proxy;
connections to other systems should or must be made directly.
In this case, add the following to the `JVM_EXTRA_ARGS` entry in the file `$TEAMSCALE_HOME/config/jvm.properties`:
(Please make sure to surround this parameter with double quotes when using the `|` character.)

```properties
"-Dhttp.nonProxyHosts=localhost|127.0.0.1|*:8080|..."
```

:::warning HTTP and HTTPS
Unlike the other properties above, the `http.nonProxyHosts` property affects *both* HTTP and HTTPS.
In particular, setting the non-existent `https.nonProxyHosts` has no effect.
:::

[jre-proxies]: https://docs.oracle.com/javase/8/docs/technotes/guides/net/proxies.html