Spring Boot Auto Configure: Proxy

This Spring Boot library provides network proxy auto-configuration.

Purpose

There are several caveats when managing network proxies in Java:

1. authentication management
   Java doesn't support any property such as (http|https|ftp).proxyHost or (http|https|ftp).proxyPort to define the username & password to use with an http proxy that requires basic authentication
2. multiple proxies
   if you run you app in an environment with several proxies (say one for the intranet, one for the internet), Java properties are not enough
3. no standard environment support
   on Linux, http_proxy, https_proxy, ftp_proxy and no_proxy environment variables are quite a standard... too bad Java doesn't support them natively

Well, this Spring Boot auto-configurer is all about those 3 points.

From the running context, it will try to discover and setup network proxy(ies) in the following way and order:

1. explicit configuration from Spring Boot configuration (yaml, properties or else),
2. implicit configuration from environment variables,
3. implicit configuration from Java properties.

Usage

Include it in your project

Maven style (pom.xml):

<repositories>
  <!-- add the Orange GitHub repository -->
  <repository>
    <id>github-orange</id>
    <url>https://maven.pkg.github.com/Orange-OpenSource/spring-boot-autoconfigure-proxy</url>
    <releases>
      <enabled>true</enabled>
    </releases>
    <snapshots>
      <enabled>false</enabled>
    </snapshots>
  </repository>
</repositories>

<dependencies>
  ...
  <dependency>
    <groupId>com.orange.common</groupId>
    <artifactId>spring-boot-autoconfigure-proxy</artifactId>
    <version>1.0.2</version>
  </dependency>
  ...
</dependencies>

Using environment variables

Proxy configuration can be implicitly set using the following environment variables:

variable	description
http_proxy or HTTP_PROXY	The proxy URL to use for http connections. Format: <protocol>://<proxy_host>:<proxy_port> or <protocol>://<user>:<password>@<proxy_host>:<proxy_port>
https_proxy or HTTPS_PROXY	The proxy URL to use for https connections. Format: <protocol>://<proxy_host>:<proxy_port> or <protocol>://<user>:<password>@<proxy_host>:<proxy_port>
ftp_proxy or FTP_PROXY	The proxy URL to use for ftp connections. Format: <protocol>://<proxy_host>:<proxy_port> or <protocol>://<user>:<password>@<proxy_host>:<proxy_port>
no_proxy or NO_PROXY	Comma-separated list of domain extensions proxy should not be used for.

See: wget documentation

Using Java properties

Proxy configuration can be implicitly set using the following Java properties:

property	description
http.proxyHost	Standard Java property defining the proxy host to use for http connections.
http.proxyPort	Standard Java property defining the proxy port to use for http connections.
http.nonProxyHosts	Standard Java property defining list of domain extensions proxy should not be used for http connections.
http.proxyUser	Non-standard Java property defining the basic authent username to use for http connections.
http.proxyPassword	Non-standard Java property defining the basic authent password to use for http connections.
https.proxyHost	Standard Java property defining the proxy host to use for https connections.
https.proxyPort	Standard Java property defining the proxy port to use for https connections.
https.nonProxyHosts	Standard Java property defining list of domain extensions proxy should not be used for https connections.
https.proxyUser	Non-standard Java property defining the basic authent username to use for https connections.
https.proxyPassword	Non-standard Java property defining the basic authent password to use for https connections.
ftp.proxyHost	Standard Java property defining the proxy host to use for ftp connections.
ftp.proxyPort	Standard Java property defining the proxy port to use for ftp connections.
ftp.nonProxyHosts	Standard Java property defining list of domain extensions proxy should not be used for ftp connections.
ftp.proxyUser	Non-standard Java property defining the basic authent username to use for ftp connections.
ftp.proxyPassword	Non-standard Java property defining the basic authent password to use for ftp connections.

See: Java Networking and Proxies documentation

Using Spring Boot configuration

Unless you have multiple proxy servers to manage, spring-boot-autoconfigure-proxy can always be used either the environment variables way or the Java properties way.

But in the other case or if you just prefer controlling your configuration, go the Spring Boot configuration way!

Here is a configuration example with a proxy for intranet addresses, and another one for internet addresses:

network:
  proxy:
    enable: true # allows disabling auto-config; enabled by default

    # explicit list of proxy servers with settings
    servers:
      # 1: the intranet proxy (doesn't require any authentication)
      -
        host: intranet.proxy.acme.com
        port: 3128
        # list of hostname matchers
        for-hosts:
          # support basic hostname
          - portal.acme.com
          # or domain name
          - .intranet.acme.com
          # or wildcards
          - "*.intranet.acme.*"
          # or even regular expressions
          - /10\.236\.\d+\.\d+/

      # 2: the internet proxy (requires an authentication)
      -
        host: internet.proxy.acme.com
        port: 8080
        username: pismy
        password: let.me.out
        # list of non-hostname matchers
        not-for-hosts:
          - localhost
          - 127.0.0.1
          - /10\.99\.\d+\.\d+/

When the application is trying to access a network resource, the URI hostname will be tested against every configured proxy one by one, if none matches then a direct connection will be used (no proxy).

Examples:

• https://www.google.com would match the internet proxy in the above configuration,
• http://10.99.101.5/path/to/a/resource would'nt match any configured proxy and would use direct connection (matches the last regex non-matcher from internet proxy),
• http://billing.intranet.acme.fr/api would match the intranet proxy (matches the 3rd wildcard matcher).

License

This code is under Apache-2.0 License