Authenticated Proxies in undetected-chromedriver: Extension or Local Forwarder

· Updated:

An undetected chromedriver proxy without a login is one flag, --proxy-server=http://IP:PORT, added to uc.ChromeOptions(). A proxy that needs a username and password takes more work, because Chrome refuses credentials in that flag and the patched driver does nothing to change it. The two approaches that hold up are a tiny Manifest V3 extension that answers the auth challenge, and a local forwarder that adds the login for Chrome.

Pair a clean fingerprint with a single-tenant IP

What undetected-chromedriver patches, and what it does not

The undetected-chromedriver package (imported as uc) downloads a matching ChromeDriver, patches out the automation markers that sites commonly look for, and launches Chrome itself with a set of arguments of its own. Everything below the browser, including DNS, TCP connections and proxy handling, is stock Chrome.

That has two consequences. First, every proxy rule that applies to Chrome applies here: one proxy per browser process, no credentials in flags, and no username and password for SOCKS proxies. Second, the package only addresses one class of signals. Sites also weigh IP reputation, request rate, account history and behavior, and none of those are touched by a patched driver. Treat it as a way to avoid being flagged for running WebDriver, not as a pass through any bot check, and keep your automation within each site's terms.

The baseline: a proxy without a login

If your proxy has no password, pass the address as a Chrome argument. The scheme describes how Chrome talks to the proxy, so http:// is correct even though the sites you open are HTTPS.

import undetected_chromedriver as uc

options = uc.ChromeOptions()
options.add_argument('--proxy-server=http://203.0.113.10:8080')

driver = uc.Chrome(options=options)
driver.get('https://api.ipify.org?format=json')
print(driver.find_element('tag name', 'body').text)
driver.quit()

Build a fresh ChromeOptions object for every uc.Chrome() call. The package mutates the options it receives and raises an error if you hand the same object to a second driver, which is easy to hit in a loop that starts one browser per proxy.

Why the login cannot go in the flag

Chrome strips user:pass@ from --proxy-server and, when the proxy answers 407, shows a native sign-in dialog that WebDriver cannot reach. The Selenium proxy guide covers this for plain ChromeDriver. Two details are specific to the undetected setup.

Selenium-wire, the usual Python shortcut, does ship a seleniumwire.undetected_chromedriver module, but it works by running a local man-in-the-middle proxy that decrypts and re-encrypts your HTTPS traffic with its own certificate. That changes the TLS handshake the site sees, which works against the reason you chose undetected-chromedriver, and selenium-wire is no longer maintained. Chrome DevTools tricks that answer Fetch.authRequired are another route, but they keep a debugging domain active for the whole session. The extension and the forwarder avoid both trade-offs.

Option 1: a Manifest V3 extension that answers the auth challenge

Current Chrome no longer runs Manifest V2 extensions, so older snippets that use a background.scripts page with webRequestBlocking fail silently. The MV3 version needs the webRequestAuthProvider permission and the asyncBlocking listener option.

Generate the extension per proxy

This helper writes a two-file extension into a temporary folder. The proxy address still comes from --proxy-server; the extension only supplies the login, and only when the challenge comes from a proxy rather than a website.

import json, tempfile, pathlib

def make_auth_extension(user: str, password: str) -> str:
    ext = pathlib.Path(tempfile.mkdtemp(prefix='proxy_auth_'))
    (ext / 'manifest.json').write_text(json.dumps({
        'manifest_version': 3,
        'name': 'Proxy auth',
        'version': '1.0',
        'permissions': ['webRequest', 'webRequestAuthProvider'],
        'host_permissions': ['<all_urls>'],
        'background': {'service_worker': 'background.js'},
    }))
    (ext / 'background.js').write_text(f'''
chrome.webRequest.onAuthRequired.addListener(
  (details, callback) => {{
    if (details.isProxy) {{
      callback({{authCredentials: {{username: {json.dumps(user)}, password: {json.dumps(password)}}}}});
    }} else {{
      callback({{}});
    }}
  }},
  {{urls: ['<all_urls>']}},
  ['asyncBlocking']
);
''')
    return str(ext)

Load it into uc, and the Chrome 137 catch

Pass the folder with --load-extension next to the proxy flag. Since version 137, branded Google Chrome ignores --load-extension, while Chromium and Chrome for Testing still honor it. If the extension does not appear, point uc at one of those builds with browser_executable_path and pin version_main to its major version so the driver matches.

import undetected_chromedriver as uc

ext_dir = make_auth_extension('USER', 'PASS')
options = uc.ChromeOptions()
options.add_argument('--proxy-server=http://203.0.113.10:8080')
options.add_argument(f'--load-extension={ext_dir}')

driver = uc.Chrome(
    options=options,
    # browser_executable_path='/opt/chrome-for-testing/chrome',
    # version_main=142,
)

An extension is also a visible part of the browser profile. It is harmless for most work, but if you would rather keep the profile clean, or you must run branded Chrome, use the forwarder below.

Option 2: a local forwarder that adds the login

A forwarder is a small proxy on your own machine that accepts connections without a password and passes them to the real proxy with the credentials attached. Chrome sees an ordinary unauthenticated proxy on 127.0.0.1, so no extension and no dialog are involved. The open-source gost tool does this in one line; other forwarders such as pproxy work the same way.

# One forwarder per upstream proxy; bind to loopback only
gost -L http://127.0.0.1:18080 -F http://USER:[email protected]:8080
import undetected_chromedriver as uc

options = uc.ChromeOptions()
options.add_argument('--proxy-server=http://127.0.0.1:18080')
driver = uc.Chrome(options=options)

Keep the listener on 127.0.0.1, never 0.0.0.0, or anyone on your network can use your paid proxy without a password. Give each upstream its own local port, start the forwarder before the browser, and stop it when the session ends so you do not collect orphaned processes. The same pattern lets Chrome use a SOCKS5 proxy with a login: forward to a socks5:// upstream and keep the local side HTTP.

Where a single-tenant IP fits a stealth-oriented setup

Once the browser stops announcing that it is automated, the IP becomes one of the louder remaining signals. Shared proxy pools often carry history from other users, and an address that changes mid-session looks odd to a site that keeps you logged in. A ProxyV4 private IPv4 or static ISP proxy has one tenant for the whole term and keeps the same address while active and when you renew, so a long-running test account or monitoring profile stays on one consistent IP.

Every proxy speaks HTTP(S) and SOCKS5 with username and password, which suits both options above, and arrives as an ip:port:user:pass line ready for the helper function. The Selenium setup guide covers the non-stealth basics with the same line. Traffic on private IPv4 and static ISP is unmetered, which helps with heavy, image-rich pages.

It is not a fit if a target only accepts mobile carrier addresses, or if you need a different IP per request; ProxyV4 does not sell mobile or rotating proxies. Nor will any IP make a script acceptable to a site whose terms forbid automation. Test one address first, then scale from the live price list.

Confirm the exit IP and look for leaks

Check the address the site sees

Load an IP echo endpoint right after the driver starts and compare it with the proxy line. If you see your own address, the flag was not applied, which usually means the options object was reused or a forwarder was not running yet. The proxy checker confirms the proxy itself works before you blame the browser.

Check WebRTC

WebRTC can reveal a local or public address outside the proxy path. Open the WebRTC leak test in the automated browser. If it shows your real address, set the Chrome preference webrtc.ip_handling_policy to disable_non_proxied_udp through your profile preferences.

Frequently asked questions

Does undetected-chromedriver support proxy authentication natively?

No. It passes your arguments to Chrome, and Chrome does not accept credentials in --proxy-server. Use an auth extension or a local forwarder.

Can I use a SOCKS5 proxy with a password in uc?

Not directly, since Chrome has no SOCKS5 username and password support. Run a local forwarder to the SOCKS5 upstream, or switch the proxy to HTTP mode, which ProxyV4 offers on the same order.

Does the auth extension work in headless mode?

With --headless=new, extensions load as in a normal window. Keep in mind that headless mode is itself easier for sites to spot than a visible browser.

Can I change the proxy without restarting the browser?

Not with --proxy-server, which is fixed at launch. Start a new driver per proxy, or point Chrome at a local forwarder and restart only the forwarder with a different upstream.

Is undetected-chromedriver still maintained?

Releases have slowed and its author has shifted attention to a successor project, so pin a known-good version and test after every Chrome update.

Pair a clean fingerprint with a single-tenant IP

Get a private IPv4 or static ISP proxy that only you use, with HTTP and SOCKS5 login on one line and the same address on renewal.

Compare plans

Related articles

Proxy setup
Selenium WebDriver and authenticated proxies: what works
Selenium proxy auth for ChromeDriver: why --proxy-server ignores user:pass, how selenium-wire or an onAuthRequired extension fixes it, and how to verify the IP.
Proxy setup
Playwright proxy authentication, one static IP per context
Give each Playwright browser context its own authenticated HTTP(S) proxy in Node.js or Python, match timezone and locale to the IP and confirm the exit address.
Free tools
Check whether WebRTC exposes the IP your proxy should hide
Free WebRTC leak test: compare the IP sites see over HTTP with the IPs your browser reveals through WebRTC STUN, and find out whether your real address leaks.
Knowledge base
HTTP or SOCKS5: Picking the Proxy Protocol Your Software Needs
HTTP vs SOCKS5 proxy in plain terms: what each protocol carries, why HTTPS works through both, where UDP matters, and how to test which one a server speaks.
Knowledge base
Configuring Proxies in Crawlee: proxyUrls, Tiers, Custom Functions and Sessions
Crawlee proxy configuration for JS and Python: proxyUrls, tieredProxyUrls, newUrlFunction and session pool binding, with code for a pool of static IPs.
Knowledge base
Sending Postman Requests Through a Proxy, With Login and Exceptions
Postman proxy settings explained: system vs custom proxy, proxy auth, the bypass list, env-variable overrides, agent caveats, and how to prove the exit IP.
Knowledge base
Chaining Burp Suite to an Upstream or SOCKS Proxy for Authorized Testing
Set a Burp Suite upstream proxy or SOCKS proxy with authentication, route only in-scope hosts, and confirm the egress IP before an authorized test starts.
Free tools
Check proxies in bulk: status, exit IP and latency
Free online proxy checker: paste up to 100 ip:port:user:pass lines and see which proxies work, their exit IP and latency, plus what each failure result means.
Products
Dedicated datacenter proxies: one private IPv4 per customer
Private IPv4 proxies in the US, Vietnam, Japan, South Korea, Singapore, the UK and Hong Kong. One tenant per IP, HTTP(S) and SOCKS5, no traffic metering.
Products
Static ISP proxies: residential IPs on consumer networks
Static ISP proxies in the United States and Vietnam: fixed IPs registered to consumer internet providers, rented to one customer, with unmetered traffic.