Tutorials 4 min read

Java HttpClient Proxy Setup with Authentication (Java 11+, 2026)

Java's built-in HttpClient supports authenticated proxies, but a default JDK setting blocks them for HTTPS. Here is the fix and the full setup.

A Java HttpClient proxy takes a ProxySelector and an Authenticator, and the code looks right on the first try. Then every HTTPS request fails with a 407 even though the credentials are correct. The cause is a JDK security default that disables Basic authentication for HTTPS tunnels. This guide covers the full setup with java.net.http.HttpClient (Java 11 and later) and that one property you have to change.

The Full Working Example

import java.net.Authenticator;
import java.net.InetSocketAddress;
import java.net.PasswordAuthentication;
import java.net.ProxySelector;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class ProxyDemo {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newBuilder()
            .proxy(ProxySelector.of(new InetSocketAddress("global.nodeproxies.xyz", 8080)))
            .authenticator(new Authenticator() {
                @Override
                protected PasswordAuthentication getPasswordAuthentication() {
                    if (getRequestorType() == RequestorType.PROXY) {
                        return new PasswordAuthentication("USERNAME-country-us", "PASSWORD".toCharArray());
                    }
                    return null;
                }
            })
            .connectTimeout(Duration.ofSeconds(15))
            .build();

        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.ipify.org"))
            .timeout(Duration.ofSeconds(30))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}

The RequestorType check makes sure your proxy credentials are only ever sent to the proxy, never to a website that asks for its own login.

The 407 Fix: jdk.http.auth.tunneling.disabledSchemes

Since Java 8u111, the JDK disables Basic authentication when tunnelling HTTPS through a proxy, through the property jdk.http.auth.tunneling.disabledSchemes, which defaults to Basic. Proxies that use username and password authentication rely on Basic, so the authenticator is never called for https:// URLs and you get a 407. Clear the property when starting the JVM:

java -Djdk.http.auth.tunneling.disabledSchemes= -jar app.jar

Setting it as a command-line flag is the reliable way. Setting it with System.setProperty only works if it runs before any HTTP class reads it, which is easy to get wrong in frameworks that initialise networking early. If plain http:// URLs also give 407, check jdk.http.auth.proxying.disabledSchemes as well. If the flag is set and you still see 407, the credentials or plan are the problem; work through how to fix proxy error 407.

Sticky Sessions: One Client per Session

HttpClient pools connections, and a pooled tunnel keeps its exit IP. Since the proxy username carries the session, give each logical session its own client:

static HttpClient clientForSession(String sessionId) {
    String user = "USERNAME-country-us-session-" + sessionId + "-time-10";
    return HttpClient.newBuilder()
        .proxy(ProxySelector.of(new InetSocketAddress("global.nodeproxies.xyz", 8080)))
        .authenticator(new Authenticator() {
            @Override
            protected PasswordAuthentication getPasswordAuthentication() {
                return getRequestorType() == RequestorType.PROXY
                    ? new PasswordAuthentication(user, "PASSWORD".toCharArray())
                    : null;
            }
        })
        .build();
}

Reuse that client for every request in the session, and drop it when you're done. Creating a new HttpClient per request is expensive and leaks threads in older JDKs. The trade-offs between sticky and rotating IPs are explained in rotating vs sticky proxies.

System Properties for Legacy Code

Older code using HttpURLConnection reads proxy settings from system properties:

java -Dhttps.proxyHost=global.nodeproxies.xyz -Dhttps.proxyPort=8080 \
     -Dhttp.proxyHost=global.nodeproxies.xyz -Dhttp.proxyPort=8080 \
     -Djdk.http.auth.tunneling.disabledSchemes= \
     -jar legacy.jar

Credentials still need a default authenticator, registered once with Authenticator.setDefault(...) using the same RequestorType check. java.net.http.HttpClient doesn't read these properties unless you use ProxySelector.getDefault().

SOCKS5 in Java

java.net.http.HttpClient doesn't support SOCKS proxies. The older socket APIs do (socksProxyHost and socksProxyPort properties), but SOCKS5 authentication through them is awkward. For HTTP traffic, use the HTTP endpoint on 8080; it tunnels HTTPS end to end. See SOCKS5 vs HTTP proxies.

Handling Status Codes

  • IOException mentioning 407 or "No credentials provided": tunnelling property not cleared, or wrong credentials.
  • 402 from the proxy: plan out of bandwidth. Don't retry.
  • 502 or 503 on CONNECT: credentials passed but the proxy couldn't reach the target. Retry with backoff or a new session.
  • HttpTimeoutException: raise the request timeout; residential exits are slower than a server connection.

Bypassing the Proxy for Some Hosts

ProxySelector.of sends everything through one proxy. For per-host decisions, implement your own selector:

import java.io.IOException;
import java.net.Proxy;
import java.net.SocketAddress;
import java.util.List;

ProxySelector selector = new ProxySelector() {
    private final Proxy upstream = new Proxy(Proxy.Type.HTTP,
        new InetSocketAddress("global.nodeproxies.xyz", 8080));

    @Override
    public List<Proxy> select(URI uri) {
        if ("internal.example.com".equals(uri.getHost())) {
            return List.of(Proxy.NO_PROXY);
        }
        return List.of(upstream);
    }

    @Override
    public void connectFailed(URI uri, SocketAddress sa, IOException e) { }
};

Pass it to HttpClient.newBuilder().proxy(selector). Internal services skip the proxy and don't count against your bandwidth.

Check the Exit IP at Startup

A one-line health check saves debugging later. When your service starts, send one request to https://api.ipify.org through the client and log the result. If the call throws a 407, the tunnelling flag is missing or the credentials are wrong, and you find out before real traffic fails. If it returns your server's own IP, the client isn't using the proxy at all, usually because a different HttpClient instance was injected.

Using Java with NodeProxies

Use ProxySelector.of(new InetSocketAddress("global.nodeproxies.xyz", 8080)), your dashboard credentials in the authenticator, and the tunnelling flag on the JVM. Datacenter proxies suit backend integrations on cooperative APIs, and residential proxies suit protected sites. Check pricing and register to get credentials.

FAQ

Why does Java HttpClient return 407 with correct proxy credentials?

Basic auth is disabled for HTTPS tunnelling by default. Start the JVM with -Djdk.http.auth.tunneling.disabledSchemes= to enable it.

Does Java HttpClient support SOCKS5?

No. java.net.http.HttpClient supports HTTP proxies only. Use the HTTP proxy endpoint instead.

Can I set a different proxy per request in Java HttpClient?

The proxy and authenticator belong to the client, so create one client per proxy configuration and reuse it.

NodeProxies

Ready to get started?

90M+ residential, mobile & datacenter proxies. Datacenter from $0.30/GB, residential from $0.42/GB. No contracts.

Create free account