Emacs 31.1 URL Proxy Login: auth-source and CONNECT Limits

The proxy's address tells Emacs where to connect. Its login is another part of the conversation. For an ordinary HTTP request, Emacs's URL library can answer a proxy authentication challenge, obtain credentials from auth-source or ask interactively, and reuse credentials held in the session.

The details below follow Emacs 31.1. They concern operations using the URL library; an external downloader launched by an Emacs package has its own authentication path.

Set the route, then let HTTP ask for the login

A fixed proxy endpoint can be selected with the documented option:

(setq url-proxy-services
      '(("http" . "proxy.example:8080")
        ("https" . "proxy.example:8080")))

Replace the placeholder with the supplied endpoint. The keys describe destination URL schemes. Adding the HTTPS entry selects a route for HTTPS destinations; it does not itself supply credentials.

During an ordinary HTTP request, a proxy can respond with 407 Proxy Authentication Required and a Proxy-Authenticate challenge. The URL library selects a supported authentication scheme and obtains credentials for the proxy endpoint. It then retries with Proxy-Authorization.

For Basic authentication, an interactive request can ask for a username and password when suitable credentials are unavailable. A request marked noninteractive cannot rely on those prompts. The proxy login is also separate from a destination website's login: a website's 401 challenge follows a different path.

Put persistent credentials in auth-source

If auth-source already reads an encrypted credential file such as ~/.authinfo.gpg, a Basic entry for this example has the following shape:

machine proxy.example port http login YOUR_LOGIN password YOUR_PASSWORD

Use your actual account and secret, and ensure the file is among your configured auth-sources. The line illustrates matching fields; it is not an instruction to put a password in your Lisp initialization file.

Two details matter in Emacs 31.1's Basic implementation. It looks up the proxy's hostname without the numeric TCP port, and it passes the proxy URL's scheme as auth-source's port value. For this HTTP proxy, that value is http, even though the TCP connection uses port 8080.

This lookup does not include the challenge's realm or the numeric proxy port. Do not expect it to select different Basic passwords for several realms or proxy ports on the same hostname. Digest uses a different host lookup, so the example above is specifically for Basic.

The URL library also keeps its own authentication cache. Its Basic entries distinguish proxy endpoints and use realm or directory matching within an endpoint; that cache is separate from the auth-source search. Typing a password at a prompt can populate the session cache without saving a new entry in your persistent credential file.

HTTPS has an earlier authentication step

For an HTTPS destination through an HTTP proxy, Emacs first sends CONNECT. Authentication may therefore be needed before it reaches the encrypted connection to the website.

In Emacs 31.1, the CONNECT request builder checks for authentication already available through its authentication machinery, including cached Basic credentials. Its Basic path does not prompt or fetch a fresh auth-source entry at that point. A non-200 CONNECT response also does not enter the ordinary HTTP 407 challenge handler described above.

Consequently, an auth-source entry that can answer a normal HTTP Basic challenge does not guarantee that a fresh session's first HTTPS request will authenticate successfully. A session with suitable cached credentials has a different starting state. Repeatedly editing the same password entry cannot by itself remove this difference between the two paths.

If an HTTPS operation stops at the proxy, establish whether CONNECT received 407 and whether you are using the behavior of this release. Confirm the proxy's offered authentication scheme as well. A Basic credential entry is not a universal adapter for every enterprise authentication system.

Keep the durable configuration in the public proxy option and your chosen credential backend. The URL library's internal Basic storage is useful for understanding this behavior, but hand-populating that private data structure would tie the setup to implementation details.