How to Configure Proxy Authentication in 6 Programming Languages

When you send requests through a proxy, your provider will usually give you a username and password.

You enter the credentials in your code, but the request returns a 407 Proxy Authentication Required error. Or the connection fails because your password contains special characters like @ or :. These are two of the most common proxy configuration issues.

This guide explains how authentication works with HTTP and SOCKS5 proxies, provides minimal configuration examples in Python, Java, cURL, Node.js, PHP, and C#, and walks you through troubleshooting 407 errors.

How Proxy Username and Password Authentication Works

Proxy authentication takes place between the client and the proxy server. It is separate from logging in to the target website. The proxy checks whether your connection is authorized, not whether you have an account on the destination site.

1. HTTP Basic Authentication

If the client sends its first request without credentials, the proxy returns a 407 response and uses the Proxy-Authenticate header to indicate which authentication scheme it supports:

HTTP/1.1 407 Proxy Authentication Required
Proxy-Authenticate: Basic realm="proxy"

The client then resends the request with credentials in the Proxy-Authorization header. The format consists of the scheme name, a space, and the Base64-encoded username:password string:

Proxy-Authorization: Basic dXNlcjpwYXNzd29yZA==

This mechanism is defined in RFC 7617, while the 407 response and Proxy-Authenticate header are defined in RFC 9110. A 401 response from the target website belongs to a different authentication layer. It requests website credentials, not proxy credentials.

2. SOCKS5 Username and Password Authentication (RFC 1929)

SOCKS5 does not parse HTTP messages, and its credentials are not sent in HTTP headers. Before establishing the TCP connection, the client and proxy negotiate an authentication method.

Once they select username and password authentication, they complete the verification process defined in RFC 1929. The SOCKS5 protocol itself is defined in RFC 1928.

Both HTTP Basic and SOCKS5 use username and password credentials, but they work at different stages: HTTP Basic uses an HTTP header, while SOCKS5 performs authentication during the handshake. This also means their troubleshooting steps differ.

3. Proxy URL Format and Special Character Encoding

A common way to configure a proxy is to include the credentials directly in the proxy URL:

http://username:password@proxy_host:proxy_port

The problem is that @, :, /, #, and ? are reserved URL characters. For example, if your password is p@ss, the parser may treat the first @ as the separator between the credentials and the host. The resulting hostname could become ss@proxy_host.

To avoid this, percent-encode the username and password separately instead of encoding the entire URL.

In Python, you can use quote to encode credentials. Setting safe to an empty string ensures that characters such as / are encoded as well:

from urllib.parse import quote

username = quote("user@name", safe="")
password = quote("pass:word", safe="")

Different libraries handle credentials differently. libcurl URL-decodes the value passed to CURLOPT_PROXYUSERPWD first, so a value like user%40name is converted back to user@name. Java and .NET authentication objects accept raw strings, so passing an encoded value makes the encoded characters part of the password.

The general rule is simple: encode credentials when embedding them in a URL, but use raw strings when passing them through a dedicated credentials object.

One more thing to keep in mind: Base64 is not encryption. It simply converts bytes into printable characters that anyone can decode. Neither HTTP Basic nor RFC 1929 encrypts the credentials themselves. Their protection depends on the security of the connection carrying them, not on the encoding.

Proxy Authentication in Different Programming Languages

All examples below send a request to https://httpbin.org/ip, which returns the IP address used for the request. This helps verify that traffic is actually going through the proxy.

The proxy host, port, and credentials in these examples are placeholders. Replace them with the values provided by your proxy provider. IPDEEP's static residential proxies and rotating residential proxies use the same username and password format.

1. Python: Requests (HTTP/HTTPS and SOCKS5)

The proxies dictionary accepts proxy URLs that include credentials. The http and https keys refer to the protocol of the target URL, not the proxy protocol. If you're accessing an HTTPS destination, you still need to configure the proxy under the https key:

import requests

proxy = "http://your_username:your_password@gateway.example.com:8080"
proxies = {"http": proxy, "https": proxy}

resp = requests.get("https://httpbin.org/ip", proxies=proxies, timeout=10)
print(resp.json())

If your username or password contains special characters, encode them as described in the previous section before adding them to the URL.

For SOCKS5, first install pip install requests[socks]. With socks5h://, DNS resolution happens on the proxy side. This is useful when you don't want to rely on local DNS:

proxies = {
    "http": "socks5h://user:password@gateway.example.com:1080",
    "https": "socks5h://user:password@gateway.example.com:1080",
}

2. Java: Apache HttpClient 4.x

CredentialsProvider supplies the login details, while HttpHost specifies the proxy. Together, they associate the credentials with the proxy server.

The example below uses org.apache.http.*, which belongs to version 4.x. Version 5.x uses the org.apache.hc.client5.* package, with different class and method names. The code below cannot be copied directly into a 5.x project:

import org.apache.http.HttpHost;
import org.apache.http.auth.AuthScope;
import org.apache.http.auth.UsernamePasswordCredentials;
import org.apache.http.client.CredentialsProvider;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.BasicCredentialsProvider;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

public class ProxyDemo {
    public static void main(String[] args) throws Exception {
        CredentialsProvider creds = new BasicCredentialsProvider();
        creds.setCredentials(new AuthScope("gateway.example.com", 8080),
                new UsernamePasswordCredentials("your_username", "your_password"));

        HttpHost proxy = new HttpHost("gateway.example.com", 8080);
        try (CloseableHttpClient client = HttpClients.custom()
                .setDefaultCredentialsProvider(creds)
                .setProxy(proxy)
                .build()) {
            System.out.println(EntityUtils.toString(
                    client.execute(new HttpGet("https://httpbin.org/ip")).getEntity()));
        }
    }
}

AuthScope limits where the credentials can be used. They are sent only when the request matches the specified host and port.

3. cURL: Command-Line Options and Environment Variables

Here are three common ways to configure a proxy, each with a single command. First, an HTTP proxy:

curl -x http://your_username:your_password@gateway.example.com:8080 https://httpbin.org/ip

Pay attention to environment variable capitalization. For security reasons in CGI environments, curl ignores the uppercase HTTP_PROXY variable because it could be injected externally. Use lowercase http_proxy instead. The uppercase HTTPS_PROXY variable is supported:

export http_proxy="http://your_username:your_password@gateway.example.com:8080"
export HTTPS_PROXY="http://your_username:your_password@gateway.example.com:8080"

curl https://httpbin.org/ip

For SOCKS5, use socks5h:// to let the proxy handle DNS resolution:

curl -x socks5h://your_username:your_password@gateway.example.com:1080 https://httpbin.org/ip

Credentials entered directly in a command may be saved in your shell history. For long-running scripts, use a restricted configuration file or a credential management tool instead.

4. Node.js: Axios + https-proxy-agent

Axios has built-in proxy settings, which can conflict with a custom Agent if both are enabled. Set proxy to false to avoid this. Since the example sends an HTTPS request, you only need to configure httpsAgent:

const axios = require('axios');
const { HttpsProxyAgent } = require('https-proxy-agent');

const proxyUrl = 'http://your_username:your_password@gateway.example.com:8080';
const agent = new HttpsProxyAgent(proxyUrl);

axios.get('https://httpbin.org/ip', { httpsAgent: agent, proxy: false })
  .then(response => console.log('Exit IP information:', response.data))
  .catch(error => console.error('Proxy connection error:', error.message));

To proxy HTTP destinations as well, create a separate Agent and assign the appropriate agents to httpAgent and httpsAgent. Also note that https-proxy-agent supports HTTP and HTTPS proxies only. For SOCKS5, use socks-proxy-agent.

5. PHP: cURL Extension

Use CURLOPT_PROXYUSERPWD to provide the username and password, and CURLOPT_PROXYAUTH to specify the authentication method:

<?php
$ch = curl_init('https://httpbin.org/ip');

curl_setopt_array($ch, [
    CURLOPT_PROXY          => 'gateway.example.com',
    CURLOPT_PROXYPORT      => 8080,
    CURLOPT_PROXYTYPE      => CURLPROXY_HTTP,
    CURLOPT_PROXYAUTH      => CURLAUTH_BASIC,
    CURLOPT_PROXYUSERPWD   => 'your_username:your_password',
    CURLOPT_RETURNTRANSFER => true,
]);

echo curl_exec($ch);

If the username contains a colon, CURLOPT_PROXYUSERPWD may split it at the wrong position. Use CURLOPT_PROXYUSERNAME and CURLOPT_PROXYPASSWORD to set them separately. If the password contains characters such as @ or %, encode them according to libcurl's requirements.

6. C#: HttpClient + WebProxy

Using WebProxy with NetworkCredential is the standard approach in .NET. The example below uses top-level statements available in .NET 6 and later:

using System;
using System.Net;
using System.Net.Http;

var proxy = new WebProxy("http://gateway.example.com:8080")
{
    Credentials = new NetworkCredential("your_username", "your_password")
};

var handler = new HttpClientHandler { Proxy = proxy, UseProxy = true };
var client = new HttpClient(handler);

Console.WriteLine(await client.GetStringAsync("https://httpbin.org/ip"));

The credentials object accepts raw strings, so percent-encoding is not required. In production, set a timeout for HttpClient and reuse the same instance.

Common Proxy Authentication Errors and How to Fix Them

1. A 407 Error Does Not Always Mean the Credentials Are Wrong

A 407 response only means that proxy authentication failed for the current connection. The quickest way to narrow down the cause is to check the Proxy-Authenticate header. Whether it specifies Basic or NTLM determines whether you should check the credentials or the authentication method.

Try the same credentials with curl -v -x. This lets you check whether the request includes the Proxy-Authorization header, which is often faster than debugging the application code.

2. SOCKS5 Authentication and Browser Limitations

Chromium-based browsers do not implement the SOCKS5 username and password authentication method. If you configure a SOCKS5 proxy that requires authentication, the handshake will fail. These browsers also do not provide a built-in field for entering SOCKS5 credentials.

You can switch to an HTTP/HTTPS proxy that supports Basic authentication or use a client or automation tool with SOCKS5 authentication support.

3. Credential Storage and Transmission

Proxy credentials are infrastructure credentials and should be handled carefully. Read them at runtime from environment variables, a secrets management service, or a configuration file with restricted access. Do not hardcode them in source code or commit them to a repository.

Logs need the same attention. Logging a full proxy URL can expose the password in plain text.

Conclusion

Most proxy authentication issues come down to protocol differences, not programming languages. HTTP proxies use the Proxy-Authorization header, while SOCKS5 authenticates during the handshake.

Encode credentials separately when embedding them in a URL, but use raw strings with dedicated credentials objects.

When you encounter a 407 error, check the authentication scheme specified in Proxy-Authenticate first, then verify the credentials and proxy address. This is more effective than repeatedly changing the password.

IPDEEP offers static and rotating residential proxies with username and password authentication, supporting HTTP, HTTPS, and SOCKS5 protocols. Check the product pages for available locations, authentication methods, and plan details.