Java HttpClient Proxy: Scoped Auth and HTTPS Tunnels
Configure a Java HttpClient proxy with scoped authentication, HTTPS CONNECT checks, timeouts, and async calls. Keep credentials out of request headers.
Instead of manually adding proxy credentials to every request, configure a Java HttpClient proxy with a ProxySelector and a scoped Authenticator, then reuse that client for your calls. This workflow covers authenticated HTTP proxies, HTTPS tunnels, timeouts, and an asynchronous variant without putting credentials in application headers.
TL;DR
- Java HttpClient proxy authentication belongs in a scoped Authenticator, not an Authorization header.
- HTTPS CONNECT authentication can fail when the Java runtime disables the proxy's authentication scheme.
- Reuse HttpClient, set explicit timeouts, and verify routing against a destination you control.
- A CONNECT tunnel to the destination does not, by itself, encrypt the earlier proxy login exchange.
Routing and authentication are separate failures
Proxy routing and proxy authentication are separate settings. A client can connect to the correct gateway and still fail because it never answers the gateway's authentication challenge.
HTTPS adds another boundary: the proxy must establish a CONNECT tunnel before the application exchanges encrypted traffic with the destination. A failure at that stage is not a destination login failure. Changing the destination's Authorization header will not fix it.
Establish one working request before adding concurrency or retries. Use the curl authenticated proxy workflow to check the endpoint independently, then reproduce the result in Java. This separates account and network problems from client configuration. Node4's rotating gateway and other HTTP/SOCKS5 proxies for scraping and automation are described on Node4's rotating proxies page.
Before you start
- Install a JDK that includes
java.net.http.HttpClient, available since Java 11. Confirm thatjavaandjavacresolve to the intended installation, especially inside containers and CI runners. - Obtain an HTTP proxy hostname, port, authentication method, and credentials. Choose a destination URL you control or have permission to request. The example reads these values from environment variables rather than embedding them in source.
- Check the HTTPS authentication restriction first. JDK networking configuration can disable Basic authentication for CONNECT tunnels through
jdk.http.auth.tunneling.disabledSchemes. Correct credentials alone do not override that policy. Confirm the permitted scheme before changing a production JVM's security settings.
The example assumes username/password Basic authentication to an HTTP proxy. It does not configure SOCKS authentication, destination authentication, or a TLS connection to the proxy itself. An HTTPS destination does not make the connection to an ordinary HTTP proxy encrypted before the tunnel exists.
Proxy endpoint and credential configuration
- Set
PROXY_HOSTto the proxy hostname only. Do not include a scheme, port, username, or password. - Set
PROXY_PORT,PROXY_USER, andPROXY_PASSseparately. - Set
TARGET_URLto your authorized test destination. Use an HTTPS destination when testing CONNECT. - Save the Java class below as
ProxyCall.java.
For a local shell, enter the values interactively:
read -r -p 'Proxy hostname: ' PROXY_HOST
read -r -p 'Proxy port: ' PROXY_PORT
read -r -p 'Proxy username: ' PROXY_USER
read -r -s -p 'Proxy password: ' PROXY_PASS
printf '\n'
read -r -p 'Authorized target URL: ' TARGET_URL
export PROXY_HOST PROXY_PORT PROXY_USER PROXY_PASS TARGET_URLUse your deployment's secret store outside a local test. Environment variables avoid committing credentials to source, but they are not a complete secret-management boundary. Restrict access to process environments, diagnostic bundles, and CI logs.
Keep the hostname exactly aligned with the endpoint configured on the client. The authenticator below deliberately refuses challenges for other hosts or ports. That restriction prevents an unrelated destination authentication challenge from receiving proxy credentials.
Expected result: your process has separate endpoint, credential, and destination values. No password appears in the command arguments or Java source.
Authenticated client configuration
- Create
ProxyCall.javawith the following contents. - Configure routing through
ProxySelector.of(...). - Scope the
Authenticatorto proxy requests, the configured endpoint, and Basic authentication. - Set a 10-second connection timeout and a 30-second request timeout. These are example limits, not performance promises.
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 ProxyCall {
private static String required(String name) {
String value = System.getenv(name);
if (value == null || value.isEmpty()) {
throw new IllegalArgumentException("Missing " + name);
}
return value;
}
public static void main(String[] args) throws Exception {
String host = required("PROXY_HOST");
int port = Integer.parseInt(required("PROXY_PORT"));
String user = required("PROXY_USER");
char[] password = required("PROXY_PASS").toCharArray();
Authenticator proxyAuth = new Authenticator() {
@Override
protected PasswordAuthentication
getPasswordAuthentication() {
if (getRequestorType() == RequestorType.PROXY
&& host.equalsIgnoreCase(getRequestingHost())
&& port == getRequestingPort()
&& "basic".equalsIgnoreCase(
getRequestingScheme())) {
return new PasswordAuthentication(user, password);
}
return null;
}
};
HttpClient client = HttpClient.newBuilder()
.proxy(ProxySelector.of(
new InetSocketAddress(host, port)))
.authenticator(proxyAuth)
.connectTimeout(Duration.ofSeconds(10))
.followRedirects(HttpClient.Redirect.NEVER)
.build();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(required("TARGET_URL")))
.timeout(Duration.ofSeconds(30))
.GET()
.build();
HttpResponse<String> response = client.send(
request, HttpResponse.BodyHandlers.ofString());
System.out.println("HTTP status: " + response.statusCode());
System.out.println("Protocol: " + response.version());
System.out.println("Body characters: " + response.body().length());
}
}Compile and run it:
javac ProxyCall.java
java ProxyCallThe authenticator responds to a challenge. It does not attach a credential header indiscriminately to every destination request. Do not replace it with a destination Authorization header or weaken the requestor check to make a failing test pass.
Redirects remain disabled intentionally. Inspect a redirect before deciding whether the next destination belongs in your workflow. Also note that ofString() buffers the response body in memory. It suits a small diagnostic response, not an unrestricted download.
Expected result: the program reports the destination response status, negotiated HTTP version, and body length without printing credentials or response content. A returned status proves that a response arrived, not that the destination accepted the request.
HTTPS tunnel policy and routing verification
- Run the program against your HTTPS test destination with the JVM's existing security configuration.
- If tunneling fails, inspect the exception and the runtime's effective networking configuration. Check
jdk.http.auth.tunneling.disabledSchemesrather than repeatedly changing the password. - If the proxy requires Basic authentication and your security policy permits it, test the following process-specific override:
java -Djdk.http.auth.tunneling.disabledSchemes= ProxyCallAn empty value removes that property's disabled-scheme list for the launched JVM. This is a security-policy change, not a routine authentication fix. Basic credentials are encoded, not encrypted. With an ordinary HTTP proxy, the CONNECT authentication exchange occurs before destination TLS protects application traffic.
Keep the override limited to a reviewed process. Do not edit a shared JDK installation merely to make one job work. Ordinary HTTP forwarding has a separate property, jdk.http.auth.proxying.disabledSchemes; changing the tunneling property does not configure every proxy authentication path.
- Confirm routing using a controlled destination that records the connecting address. Compare a direct request with the proxied request in that destination's logs.
- Record the JDK vendor, full runtime version, authentication scheme, and launch flags with the test result. Those details make a container rebuild reproducible.
A successful HTTP status alone does not identify the exit address. Destination-side observations provide that evidence. They also help distinguish a wrong route from a valid proxy request that the destination rejects.
Expected result: HTTPS requests either complete through the intended proxy under an approved authentication policy, or fail with a specific, reproducible tunnel error. You have not disabled destination certificate verification.
Send asynchronous calls with the same proxy
Best for independent requests: use sendAsync() when your application needs a future instead of blocking its calling thread. Keep send() for a straightforward diagnostic path. Both use the same client-level proxy and authenticator settings.
Replace the synchronous send and output statements with:
var pending = client.sendAsync(
request, HttpResponse.BodyHandlers.ofString());
pending.thenAccept(response -> {
System.out.println("HTTP status: " + response.statusCode());
System.out.println("Body characters: " + response.body().length());
}).join();The final join() keeps this command-line program alive until completion. It also blocks that thread, so this replacement demonstrates the asynchronous API rather than a concurrent pipeline. In a service, return or compose the future instead of immediately joining it.
Reuse the configured client across requests with the same routing and credential requirements. HttpClient is immutable and supports concurrent requests. Creating one client per URL discards the benefits of client reuse and makes configuration harder to audit.
Bound concurrency before submitting a batch. An executor setting alone is not an in-flight request limit. Use a bounded work queue or application-level permits, and release permits on both successful and exceptional completion. Asynchronous submission does not remove proxy connection limits or destination rate limits.
The trade-off is additional lifecycle and error handling. Futures can complete exceptionally, and response status codes still need application checks. Establish a small controlled batch before increasing the submission limit.
Troubleshooting authenticated proxy calls
Proxy authentication fails or returns 407
Check the endpoint, authentication method, and exact username format first. Then verify that the challenge is Basic and matches the host and port allowed by the authenticator. Tunnel failures can surface as exceptions rather than ordinary response objects.
Do not log the password while debugging. Capture the exception type, sanitized message, runtime version, and whether the failure occurred during CONNECT. Separate a rejected credential from a disabled authentication scheme.
The destination returns 401, 403, or 429
A 401 concerns destination authentication, not proxy authentication. A 403 is a refusal that needs investigation; it does not prove that the proxy configuration is broken. A 429 indicates rate limiting.
Inspect the destination response and applicable access policy. Reduce request pressure when rate limited, honor Retry-After when supplied, and do not treat changing exits as permission to ignore restrictions.
The request times out
Separate connection establishment from the full request. The sample's 10-second connect timeout applies when a connection must be established; its 30-second request timeout limits the request. Neither value diagnoses the failed network hop by itself.
Check DNS, gateway reachability, destination reachability, and firewall policy. Do not retry indefinitely. Retry only operations whose semantics permit repetition, with a bounded attempt count and delay.
TLS validation fails after CONNECT
Keep certificate validation enabled. Check the destination hostname, certificate chain, system clock, and any approved interception infrastructure. An HTTP proxy does not justify a trust-all SSLContext.
If a corporate network performs TLS inspection, use its approved trust configuration. Do not silently replace the application's trust decisions with an accept-everything callback.
A SOCKS endpoint does not work
The example configures an HTTP proxy. java.net.http.HttpClient does not provide SOCKS proxy support through this configuration. Replacing the endpoint with a SOCKS port does not convert the HTTP CONNECT exchange into SOCKS negotiation.
Use an HTTP endpoint for this workflow. If SOCKS is mandatory, choose a client stack with documented SOCKS support and verify its authentication behavior separately.
Customize your workflow
Move the working configuration into a reusable client factory. Keep credentials isolated by tenant or project, and replace the client when its immutable routing or authentication configuration changes. Avoid a global default authenticator for unrelated application traffic.
Add structured logs for destination host, status, elapsed time, exception class, and a non-secret route identifier. Exclude passwords, authentication headers, and sensitive query strings. Maintain a sanitized deployment record rather than retaining raw debug traffic.
For stateful collection, define cookie handling and exit continuity together. Reusing a Java client does not guarantee a stable exit when the gateway rotates addresses. Session behavior belongs to the proxy service configuration, not the connection pool.
Keep retries separate from rotation. A failed request needs classification before either action. Retrying an accepted write can duplicate work, while changing an exit can disrupt a session that depends on continuity.
FAQ
How do I configure a Java HttpClient proxy with a username and password?
Set a ProxySelector on HttpClient.Builder and attach an Authenticator scoped to the proxy endpoint. Return PasswordAuthentication only for the intended proxy host, port, and supported authentication scheme.
Why does my Java proxy work for HTTP but fail for HTTPS?
HTTPS requires a CONNECT tunnel, whose authentication can be restricted by the JVM's tunneling policy. Inspect jdk.http.auth.tunneling.disabledSchemes and the tunnel error before changing credentials.
Should I add a Proxy-Authorization header manually?
Use a scoped Authenticator for this workflow instead of manually attaching Proxy-Authorization. Let the client handle the proxy challenge, and keep proxy credentials separate from destination Authorization headers.
Does Java HttpClient support SOCKS5 proxies?
The java.net.http.HttpClient configuration shown here supports HTTP proxies, not SOCKS5. Use an HTTP endpoint or a different client stack with documented SOCKS support.
Can I reuse an authenticated HttpClient for asynchronous requests?
Yes. sendAsync uses the same client-level proxy selector and authenticator as send. Reuse the client and impose an application-level limit on in-flight work.
Does a successful response prove the proxy exit address?
No. Verify the connecting address using logs from a destination you control. A successful status establishes response delivery, not the identity or location of the exit.
Is clearing the disabled tunneling schemes property safe?
Clearing the property changes the launched JVM's authentication restrictions and requires a security review. Basic proxy credentials sent to an ordinary HTTP proxy are not encrypted by the destination's later TLS tunnel.
Does a successful CONNECT tunnel mean the proxy login itself was encrypted?
No. A successful CONNECT tunnel does not make the earlier proxy login exchange encrypted. That distinction is easy to miss because the destination URL starts with HTTPS. Before production, check both boundaries: how the application authenticates to the proxy, and how it validates the destination's TLS certificate.
Related guides
- Rotating proxies for web scraping
- Proxy rotation when a request gets blocked
- Go net/http proxy authentication, the same scoped-authentication and CONNECT-tunnel workflow built with Go's
http.Transportinstead of Java's HttpClient