Proxy Authentication: Username and Password or an IP Allowlist
Contents

In short: A proxy recognises you by a username and password, or by the address you connect from, checked against an IP allowlist. A password works from any network, so it suits laptops and people who move. An allowlist keeps the secret off the client, so it suits servers with a fixed address and tools that cannot send a password, such as Chrome over SOCKS5. On a ProxyJam order, a non-empty allowlist switches the password off.
A proxy has to know that a connection is yours before it forwards it. There are two ways to tell it: send a username and password, or connect from an address the proxy already knows. Both are called proxy authentication, and they fail in different places. This guide shows when each is the simpler choice, how to set each one up in a browser, in Python requests, in Selenium and in Playwright, and which error each mistake produces.
How does a proxy know a request is yours?
By what the client sends with the connection, or by the address the connection comes from.
With a username and password, the proxy answers a request that carries no
credentials with status 407, Proxy Authentication Required. Your client then sends
it again with a Proxy-Authorization header, as
RFC 9110 describes.
SOCKS5 has a sign-in of its own, defined in
RFC 1929, which a client has to
implement separately.
With an IP allowlist, the proxy compares the address a connection arrives from with a list you gave it. A listed address gets through with no credentials. Any other address is refused. This is the proxy’s own list. The reverse case, where your systems admit only a few addresses and the proxy supplies one of them, is covered in a static IP for IP allowlisting.
Every static IP you buy from ProxyJam has its own host, port, username and password, shown under My Proxies in the dashboard. An order starts on the password. You can give it an allowlist of IPv4 addresses instead, and while the list holds an address the password stops working for that order. Sending an empty list turns the password back on. The two methods take turns on one order, so pick per order, or keep one order per method.
When is a username and password simpler?
If the machine that connects does not keep one public address, a password is the easier choice. Most home connections get their address from the internet provider and can receive a new one after a router restart. A laptop takes a different address in every café, office and hotel, and a phone hotspot often shares one address among many subscribers. An allowlist would have to follow every one of those changes by hand, and each change locks you out until you update it.
A password goes wherever the client goes. It also suits a team spread over several cities, because nobody has to report their address before they can work. The cost is the secret itself: it has to be stored somewhere, it can be copied, and everyone who has it uses the same login.
When is an IP allowlist simpler?
An allowlist is simpler if the client has a fixed public address, or cannot send a password at all.
A server or a CI runner with a fixed public address is the plain case. The proxy admits it, and no credentials sit in its configuration, its logs or its command history.
The second case is a tool that cannot answer a password prompt:
- Chrome and Edge over SOCKS5. Chromium’s proxy notes say no authentication method is supported for SOCKS5 in Chrome, so a SOCKS5 password is never sent.
- Selenium driving Chrome. Chrome drops credentials written into
--proxy-server, and in our tests both WebDriver BiDi handlers timed out. - Playwright over SOCKS5. All three engines refuse to launch with a SOCKS5 username and password.
Two limits come with it. Hosted CI runners often leave from a different address on each run, so check what yours does before you rely on it. And the proxy sees only the address, so everyone who shares it gets in: every device behind an office router, or every customer behind a provider’s shared address. List only addresses whose users you know, and remove an entry the day it stops being yours.
How do you set up each method?
The four values are the same everywhere: host, port, and either a username and password or nothing at all. Only the place they go differs. Our integration guides carry tested code for each tool; the short versions follow.
In Chrome, Edge or Firefox with ProxyJam Connector
Chrome reads no credentials from its proxy settings and asks in a dialog instead. ProxyJam Connector, our free extension, answers that dialog for you. Sign in to your ProxyJam account in it and press Connect beside a proxy, or add a profile by hand with the host, port, username and password. On Chrome and Edge it answers once you grant network access on its Settings page.
For an allowlist, open the proxy’s Manage dialog in the extension and fill in Allowed IP addresses, one per line. Leaving the field empty returns the order to its username and password.
In Python requests
requests takes the credentials inside the proxy URL. Keep them out of the script and read them from the environment:
import os
from urllib.parse import quote
import requests
user = os.environ["PROXY_USER"]
password = quote(os.environ["PROXY_PASSWORD"], safe="")
proxy = "http://" + user + ":" + password + "@HOST:PORT"
r = requests.get("https://example.com/", proxies={"http": proxy, "https": proxy}, timeout=30)
quote matters when the password holds a slash, a question mark, a hash or a
percent sign, which would otherwise break the URL. With an allowlist the URL is
just http://HOST:PORT. The requests guide
adds sessions, and SOCKS5 with the proxy resolving hostnames.
In Selenium
For Chrome, use the allowlist and pass the address without credentials:
from selenium import webdriver
options = webdriver.ChromeOptions()
options.add_argument("--proxy-server=http://HOST:PORT")
driver = webdriver.Chrome(options=options)
Firefox under Selenium can send a username and password through a WebDriver BiDi authentication handler. The Selenium guide has both samples, with the versions we tested them on.
In Playwright
Playwright takes the username and password in fields of their own, never inside the server URL:
browser = playwright.chromium.launch(proxy=dict(
server="http://HOST:PORT",
username=os.environ["PROXY_USER"],
password=os.environ["PROXY_PASSWORD"],
))
Over SOCKS5, pass only server="socks5://HOST:PORT" and use the allowlist.
The Playwright guide covers a proxy per
context and the results for all three engines.
What errors does each method produce?
A rejected password and a missing one look alike: the proxy answers 407. How that reaches you depends on the client.
- Chrome shows its sign-in dialog, and shows it again after each rejected attempt. The post on why Chrome keeps asking for proxy credentials explains the loop.
- ProxyJam Connector stops after the proxy rejects the stored credentials twice for one request, and its toolbar badge shows AUTH.
- requests returns a response with status 407 for an
http://address. For anhttps://address the tunnel through the proxy fails, and requests raises aProxyErrorwhose message carries the 407. - Selenium with Chrome loads no page when the credentials sit in
--proxy-server, which reads like a network fault. - Playwright with credentials written into the server URL hung on its first navigation in our test, with no message about the password.
An allowlist fails in its own ways:
- The address changed. A new public address is not on the list, so the proxy refuses the connection. Look the address up again and update the list.
- The list was set, and another client still uses the password. Setting the allowlist for a server switches the password off for the whole order, laptops included. Keep those clients on a second order, or add their addresses too.
- The list was replaced by accident. Each call sends the full list, so an update that names only the new address drops the old ones.
How do you keep proxy credentials safe?
Treat the proxy password like any other password. Keep it out of the code and out of the repository: read it from an environment variable or a secrets manager, as the Twelve-Factor App and the OWASP secrets cheat sheet recommend. A proxy URL with a password in it ends up in logs, crash reports and shell history, so print the host and port, never the whole URL.
The API key is a separate secret and a larger one. It reaches your account, and a key with the right scope can spend from your wallet. Give each script or teammate a key of its own, so that removing one leaves the others working. Delete a key on the API Keys page of the dashboard the day the person or script that used it leaves.
The proxy password is harder to take back. Our API reference lists no call that changes it for a static residential (ISP) proxy. If someone who knew it leaves, the lever you hold is the allowlist: set it to the addresses you still use, and the old password stops working for that order.
When is a ProxyJam proxy the wrong fit?
It is the wrong fit if you need a separate login for each person on one address. Each static IP has one username and one password, so per-person access means one address per person, or an allowlist entry per person’s fixed address.
It also does not fit work that needs a new address for every request. That takes a rotating pool, and ProxyJam does not sell one today. What we sell is static residential (ISP) proxies: one address on a named internet provider’s network, yours for the period you pay for, with prices on the pricing page. If you already have one, using your static IP after purchase shows where its details are in the dashboard.
