What is proxy authentication?
Definition
How a proxy decides you may use it: credentials in a Proxy-Authorization header, or a list of allowed source addresses. A 407 means it said no.
There are two models. Either every request carries credentials in a Proxy-Authorization header, or the proxy accepts anything arriving from an address you registered in advance, which is IP whitelisting. Some services accept both. This entry is about the first; the full troubleshooting path for a refused request lives in the 403 vs 407 vs 429 guide.
The challenge and the answer
RFC 9110 defines the exchange. A proxy that wants credentials and did not get valid ones answers 407 Proxy Authentication Required, and it must include at least one Proxy-Authenticate header naming the scheme it accepts. The client may then repeat the request with Proxy-Authorization. Here is a local test proxy refusing curl 8.7.1, then accepting it:
$ curl -sv -o /dev/null -x http://127.0.0.1:38521 https://example.com/
> CONNECT example.com:443 HTTP/1.1
> Host: example.com:443
< HTTP/1.1 407 Proxy Authentication Required
< Proxy-Authenticate: Basic realm="lab"
$ curl -sv -o /dev/null -x http://127.0.0.1:38521 -U user:pass https://example.com/
> CONNECT example.com:443 HTTP/1.1
> Host: example.com:443
> Proxy-Authorization: Basic dXNlcjpwYXNz
With -U, curl sent the header on its first attempt; the proxy logged a single CONNECT, with no challenge round trip. Also notice how little is hiding in that header:
$ printf 'user:pass' | base64
dXNlcjpwYXNz
Basic is an encoding, not encryption. RFC 7617 says so directly: the scheme is not a secure method of user authentication unless something like TLS protects it, because the user ID and password cross the network as cleartext. Through an ordinary http:// proxy URL, anyone on the path to the proxy can read them. curl can wrap the hop to the proxy itself in TLS with an https:// proxy URL, which its manual dates to 7.52.0 for OpenSSL and GnuTLS builds, but the proxy has to offer TLS on that port.
Basic is not the only scheme a proxy can name in its challenge. Office and corporate proxies can ask for Digest, NTLM or Negotiate instead, and a client that only knows Basic fails against them with a 407 that looks exactly like a wrong password. Read the scheme in the Proxy-Authenticate line before you suspect the credentials. curl has a flag for each (--proxy-digest, --proxy-ntlm, --proxy-negotiate), and --proxy-anyauth lets it pick, which its manual warns can cost an extra round trip.
The same 407, four different errors
What you search for depends on the client, because a 407 during CONNECT happens before any HTTPS request exists to carry a status. We pointed three clients at the same refusing proxy, and checked curl’s source for the newer behaviour:
| Client and target | What it reported |
|---|---|
| curl 8.7.1, https:// URL | curl: (56) CONNECT tunnel failed, response 407, exit status 56 |
| curl 8.20.0 or later, https:// URL | The same message with exit status 7, per curl’s source from that release on; we did not run this build |
| curl 8.7.1, http:// URL | An ordinary response with status 407, exit status 0 |
| Python 3.15 urllib, https:// URL | urllib.error.URLError: <urlopen error Tunnel connection failed: 407 Proxy Authentication Required> |
The Python case is the one that costs time. It arrives as a URLError, the same exception class as a DNS failure or a refused connection, not as an HTTPError with a status code, so code that branches on status never sees a 407 at all. Match on the message, or test the proxy with curl first.
407 is the proxy, 401 is the site
A 407 carries Proxy-Authenticate and means the destination was never contacted. A 401 carries WWW-Authenticate, comes from the site, and means the proxy worked and the site wants its own login. RFC 9110 also scopes the proxy header tightly: Proxy-Authorization is consumed by the first proxy that asked for it, so in a chain of proxies each hop that demands credentials needs its own unless they deliberately relay them.
Why the username carries more than a name
A gateway hostname is fixed, so many providers encode routing in the username: country, city, a session label. The syntax is provider-specific, and it has a security cost. That string is now configuration, so it gets pasted into code, CI variables and tickets, and a full URL with the password in it gets copied into logs, error messages and shell history. Keep the password out of URLs where the client allows it, and never log the complete credential.
The curl guide shows the inline and separate-flag forms side by side, and proxies in Python covers where requests, httpx and aiohttp take the credential.
Frequently asked questions
What is the difference between 401 and 407?
Why does my provider put a country code in the username?
Is Basic proxy authentication secure?
Sources
Also covered in
- Proxy authentication error (407): exact messages and fixes
- 4. Proxy causes: CONNECT, authentication, interception and upstream refusalin Connection reset by peer: what it means and how to fix it