Selenium Proxy Authentication in Python: Tested Chrome Setup

Choose an authentication method your browser supports

For an endpoint authorized by your outbound IP, configure the proxy host and port before starting the browser. Selenium’s driver options documentation shows the standard manual proxy capability. The allowlist must contain the address that actually reaches the provider, which can differ between a laptop and a hosted runner.

A username and password require an additional authentication flow. Chromium’s proxy documentation says Chrome ignores credentials embedded in manual proxy settings. Consequently, putting user:password@ in --proxy-server is not a working authentication recipe.

Chrome also does not support SOCKS5 proxy authentication. An HTTP proxy endpoint with supported authentication is a different choice from a SOCKS5 endpoint that requires a password. Confirm the protocol in the provider’s connection details before debugging Selenium.

Install and record the tested versions

The example below was checked on October 11, 2026 with Selenium 4.51.0, Python 3.12 and Chrome 155.0.8059.39. Use an isolated environment:

python -m venv .venv
# Activate .venv using the command for your shell.
python -m pip install selenium==4.51.0

Install Chrome on the runner. Selenium Manager can resolve the matching driver when one is not supplied; its download access is a separate network requirement from the browser’s proxy route.

The code uses the released binding’s start_devtools() implementation to receive authentication events. Selenium describes CDP support as browser-version-dependent while WebDriver BiDi develops. Record the browser version in your test output and rerun the authentication fixture after either dependency changes. This is not a Firefox or Safari example.

Answer the proxy challenge without sharing credentials with a website

Set PROXY_SERVER to an HTTP endpoint such as http://proxy.example:8080. Supply PROXY_USERNAME and PROXY_PASSWORD through your process environment or secret manager. Save this as selenium_proxy_check.py:

import ipaddress
import json
import os
from urllib.parse import urlsplit
from selenium import webdriver
from selenium.webdriver.common.by import By


def check_exit(proxy_server, username, password,
               target='https://api.ipify.org?format=json'):
    proxy = urlsplit(proxy_server)
    if (proxy.scheme != 'http' or not proxy.hostname or not proxy.port
            or proxy.username or proxy.password or proxy.path not in ('', '/')
            or proxy.query or proxy.fragment):
        raise ValueError('Use an HTTP proxy URL with host and port only')
    options = webdriver.ChromeOptions()
    options.add_argument('--headless=new')
    options.add_argument(f'--proxy-server={proxy_server}')
    driver = webdriver.Chrome(options=options)
    try:
        driver.set_page_load_timeout(30)
        devtools, connection = driver.start_devtools()
        attempted = set()

        def authenticate(event):
            challenge = event.auth_challenge
            origin = urlsplit(challenge.origin)
            is_expected_proxy = (
                challenge.source == 'Proxy'
                and origin.hostname == proxy.hostname
                and (origin.port or 80) == proxy.port
            )
            if is_expected_proxy and event.request_id not in attempted:
                attempted.add(event.request_id)
                response = devtools.fetch.AuthChallengeResponse(
                    response='ProvideCredentials',
                    username=username, password=password)
            else:
                response = devtools.fetch.AuthChallengeResponse(
                    response='CancelAuth')
            connection.execute(devtools.fetch.continue_with_auth(
                event.request_id, response))

        connection.add_callback(devtools.fetch.AuthRequired, authenticate)
        connection.add_callback(devtools.fetch.RequestPaused, lambda event:
            connection.execute(devtools.fetch.continue_request(event.request_id)))
        connection.execute(devtools.fetch.enable(handle_auth_requests=True))
        driver.get(target)
        data = json.loads(driver.find_element(By.TAG_NAME, 'body').text)
        return str(ipaddress.ip_address(data['ip']))
    finally:
        driver.quit()


if __name__ == '__main__':
    try:
        print(check_exit(os.environ['PROXY_SERVER'],
                         os.environ['PROXY_USERNAME'],
                         os.environ['PROXY_PASSWORD']))
    except Exception as exc:
        raise SystemExit(f'Proxy check failed ({type(exc).__name__})')

Run python selenium_proxy_check.py. The default ipify endpoint returns the observed address for that request. The script validates its response as an IP address and closes the browser in finally.

The DevTools Fetch protocol reports whether the challenge came from a proxy or server and identifies the challenger’s origin. The handler checks those fields, submits credentials once per request, and cancels an unexpected or repeated challenge. It also continues paused requests so interception does not leave navigation waiting indefinitely.

This example deliberately rejects credentials inside the server URL. It accepts an HTTP proxy; an HTTPS destination still uses the proxy’s CONNECT tunnel. Basic credentials on the client-to-proxy HTTP connection are not encrypted by that destination’s TLS. Choose an appropriately protected connection to your proxy for the environment you operate.

What the local test established

We ran the published function against a local HTTP proxy fixture. The fixture accepted its expected Basic proxy credentials and returned a valid IP-shaped response. A second case returned a website-style 401 challenge after proxy authentication; no origin Authorization header containing the proxy credentials was sent. Wrong proxy credentials were cancelled instead of being retried without a bound.

These checks cover the displayed Python code, Chrome’s proxy challenge and failure cleanup. They do not establish a commercial endpoint’s speed, certificate handling, HTTPS CONNECT behavior or acceptance by a target website. Verify those properties in your own authorized staging environment before expanding a job.

A successful IP check only identifies that browser request’s exit. For WebRTC diagnostics use the browser ICE test, and for request status and content checks use an endpoint you control. Avoid using an account login as the first connectivity test.

Why an unrestricted authentication helper needs care

Selenium 4.51.0 includes callback-based authentication handlers. Its released authentication wrapper exposes request URL, realm and scheme. These fields alone do not identify a proxy challenge: a destination can request its own credentials using the same authentication scheme.

The Chrome example therefore uses the explicit challenge source and origin available through DevTools. Do not replace that check with an unrestricted helper that supplies the proxy password whenever authentication is requested. If you adopt WebDriver BiDi, inspect the capabilities of your installed binding and test both a proxy 407 and a destination 401 before using it with real credentials.

For browser pools, use an isolated browser session for each configured endpoint. Sharing a profile can retain cookies and authentication state across jobs. Playwright’s context guide covers an alternative when per-context routing fits the application.

Diagnose failures at the correct connection

If Chrome reports ERR_PROXY_CONNECTION_FAILED, check that the browser host can resolve and reach the endpoint. A connection test from the Python process is useful evidence, but a remote browser may run on another machine. If the proxy repeatedly asks for credentials, check the endpoint’s protocol and authorization policy before changing the destination URL.

A website’s 403 response does not mean the proxy password was wrong. Preserve the destination response and investigate the site’s access rules. Our proxy error reference separates HTTP status codes; the IP restriction guide covers account and network diagnosis.

For an AI browser worker, place these settings in the process that launches the browser. An LLM API client, the Selenium control connection and the browser’s web requests can use different routes. Keep proxy secrets out of prompts and browser-visible page content. Give the worker an explicit navigation deadline and require a useful response, rather than treating a loaded error page as a completed task.

Frequently asked questions