Autenticação de Proxy no Selenium: 4 Configurações que Realmente Funcionam
O Chrome exibe uma caixa de diálogo de autenticação que o Selenium não consegue manipular, e o truque de credenciais na URL falha silenciosamente. Aqui estão as quatro configurações que realmente autenticam um proxy no Selenium — classificadas por quão pouco elas irão prejudicar.
A autenticação de proxy no Selenium é uma armadilha disfarçada de uma linha de código. A flag --proxy-server do Chrome aceita um endereço de proxy alegremente — e ignora silenciosamente qualquer nome de usuário e senha que você embutir. O Chrome então exibe uma caixa de diálogo de autenticação nativa que o WebDriver não consegue ver, seu script trava, e a principal resposta do Stack Overflow que você encontra (113+ votos) resolve isso com uma extensão Manifest V2 que o Chrome moderno não carrega mais. Este guia cobre as quatro configurações que autenticam um proxy no Selenium hoje — lista branca de IPs, uma extensão Manifest V3, selenium-wire, e saber quando entregar todo o problema do navegador a uma API.
Por que a autenticação básica de proxy no Selenium falha
Três fatos explicam todas as tentativas fracassadas. Primeiro, o Chromium remove credenciais de --proxy-server=http://user:pass@host:port — o formato da flag simplesmente não tem suporte a credenciais. Segundo, o desafio 407 Proxy Authentication Required do proxy aparece como uma caixa de diálogo nativa, fora do DOM, onde send_keys não consegue alcançar. Terceiro, a antiga rota DesiredCapabilities (socksUsername / socksPassword) só se aplicava a proxies SOCKS e nunca funcionou para HTTP — a configuração que 'parece certa' e não faz nada. Portanto, as opções reais evitam completamente a caixa de diálogo.
Método 1: Lista branca de IPs — zero código, zero caixas de diálogo
Se o seu scraper roda em uma máquina com um IP público estável, ignore as credenciais completamente: registre esse IP no painel do seu provedor de proxy, e o gateway autentica você pelo endereço de origem. Todo plano da QuantumProxies suporta lista branca de IPs junto com user:pass. O lado do Selenium se torna a flag simples — que sempre funcionou bem sem autenticação:
from selenium import webdriver
options = webdriver.ChromeOptions()
options.add_argument("--proxy-server=http://gate.quantumproxies.io:PORT")
options.add_argument("--headless=new")
driver = webdriver.Chrome(options=options)
driver.get("https://httpbin.org/ip")
print(driver.find_element("tag name", "body").text) # proxy exit IP
driver.quit()Sempre verifique a saída antes de confiar em uma execução: carregue um endpoint de eco de IP e confirme que o endereço pertence ao proxy, porque uma flag mal configurada falha silenciosamente e o Chrome simplesmente conecta diretamente. O limite da lista branca é topológico: ela autentica uma máquina, não um script. Runners em nuvem efêmeros, contêineres atrás de NAT e máquinas CI com IPs mutáveis precisam de um dos métodos abaixo.
Método 2: uma extensão Chrome Manifest V3
A correção clássica gera uma pequena extensão Chrome que define o proxy e responde ao desafio de autenticação via chrome.webRequest.onAuthRequired. O famoso snippet de 2019 usa Manifest V2, que o Chrome agora aposentou — a versão moderna precisa de manifest_version: 3, um service worker, e a permissão webRequestAuthProvider. Isso constrói e carrega uma em tempo de execução:
import json, os, tempfile
from selenium import webdriver
HOST, PORT = "gate.quantumproxies.io", "PORT"
USER, PASS = "USER", "PASS"
manifest = {
"name": "Proxy Auth", "version": "1.0", "manifest_version": 3,
"permissions": ["proxy", "webRequest", "webRequestAuthProvider"],
"host_permissions": ["<all_urls>"],
"background": {"service_worker": "worker.js"},
}
worker = """
chrome.proxy.settings.set({
value: { mode: "fixed_servers", rules: {
singleProxy: { scheme: "http", host: "%s", port: parseInt("%s") },
bypassList: ["localhost"] } },
scope: "regular"
}, function() {});
chrome.webRequest.onAuthRequired.addListener(
function(details) {
return { authCredentials: { username: "%s", password: "%s" } };
},
{ urls: ["<all_urls>"] },
["blocking"]
);
""" % (HOST, PORT, USER, PASS)
ext_dir = tempfile.mkdtemp()
with open(os.path.join(ext_dir, "manifest.json"), "w") as f:
json.dump(manifest, f)
with open(os.path.join(ext_dir, "worker.js"), "w") as f:
f.write(worker)
options = webdriver.ChromeOptions()
options.add_argument("--load-extension=" + ext_dir)
options.add_argument("--headless=new")
driver = webdriver.Chrome(options=options)
driver.get("https://httpbin.org/ip")Dois riscos. Extensões só carregam no novo modo headless — o simples --headless falha com um erro críptico 'falha ao esperar pela página de fundo da extensão', então --headless=new é obrigatório. E carregar um diretório descompactado via --load-extension é mais confiável em versões do Chrome do que empacotar um zip. Se você preferir não manter isso, o pacote selenium-authenticated-proxy no PyPI gera a extensão para você a partir de uma única URL de proxy.
Método 3: selenium-wire, e suas concessões
O selenium-wire envolve o WebDriver com um proxy local man-in-the-middle, o que torna proxies upstream autenticados — incluindo SOCKS5 — um simples dicionário de opções:
# pip install selenium-wire
from seleniumwire import webdriver
options = {
"proxy": {
"http": "http://USER:PASS@gate.quantumproxies.io:PORT",
"https": "http://USER:PASS@gate.quantumproxies.io:PORT",
"no_proxy": "localhost,127.0.0.1",
}
}
driver = webdriver.Chrome(seleniumwire_options=options)
driver.get("https://httpbin.org/ip")Saiba o que você está comprando. O projeto foi arquivado pelo seu mantenedor no início de 2024 e não recebe atualizações, e porque ele descriptografa o tráfego localmente, o alvo vê o handshake TLS do selenium-wire em vez do do Chrome — uma incompatibilidade que sistemas de impressão digital JA3/JA4 sinalizam mesmo quando seu IP está impecável. Ele continua sendo genuinamente útil para inspeção de requisições durante o desenvolvimento e para o Firefox, onde o truque da extensão não existe. Para scraping em produção em sites protegidos, prefira os métodos 1-2, ou suba um nível.
Firefox, e a lacuna de autenticação
O Firefox aceita um proxy não autenticado de forma limpa através das preferências do perfil (network.proxy.type = 1 mais configurações de host e porta), mas não tem equivalente ao truque da extensão do Chrome para responder à caixa de diálogo de credenciais a partir do WebDriver. Na prática, os usuários do Firefox escolhem lista branca de IPs ou selenium-wire. Se sua única razão para o Firefox era seu manuseio de proxy, essa razão não se sustenta mais.
Quando parar de remendar o Selenium e mudar para uma API
A autenticação é o primeiro imposto, não o último. Uma instância do Chrome custa centenas de MB de RAM, então algumas dezenas de sessões concorrentes saturam um servidor; as versões do ChromeDriver acompanham os lançamentos do Chrome; e os fornecedores de anti-bot detectam o Selenium padrão independentemente do IP por trás dele — navigator.webdriver e artefatos do CDP o denunciam. Duas atualizações mudam a economia. Primeiro, execute seus navegadores através de proxies residenciais para que a reputação do IP deixe de ser a razão pela qual você é bloqueado — mais de 90 milhões de IPs domésticos com rotação por requisição ou sessões fixas para fluxos logados. Segundo, quando manter navegadores deixa de valer a pena, uma Scraper API colapsa toda a pilha em uma única chamada HTTP: ela renderiza JavaScript sob demanda, gerencia IPs e tentativas internamente, e retorna HTML, markdown ou JSON estruturado. O mesmo trade-off se aplica aos primos do Selenium — veja nossos guias para integração de proxy Playwright e configuração de proxy Puppeteer antes de assumir que uma mudança de framework resolverá um problema de detecção.
Perguntas frequentes
Como configuro um proxy com autenticação no Selenium ChromeDriver?
Ou liste o IP da sua máquina com o provedor de proxy e passe uma flag simples --proxy-server, ou carregue uma pequena extensão Manifest V3 que define o proxy e fornece credenciais através de chrome.webRequest.onAuthRequired. Embutir user:pass@ na flag não funciona — o Chromium ignora.
Por que o Chrome mostra uma janela de login de proxy com o Selenium?
O proxy respondeu com 407 e o Chrome está pedindo credenciais a um humano. A caixa de diálogo é uma interface nativa, invisível para o WebDriver, então nenhum seletor ou chamada send_keys pode preenchê-la. A solução é autenticar antes que a caixa de diálogo possa aparecer: lista branca de IPs, uma extensão de autenticação, ou uma camada MITM como o selenium-wire.
O selenium-wire ainda funciona em 2026?
Ainda é instalado e funciona para muitas cargas de trabalho, mas o projeto foi arquivado no início de 2024 e não recebe manutenção. Seu design MITM também substitui a impressão digital TLS do Chrome por uma em Python, que sistemas modernos de anti-bot detectam. Trate-o como uma ferramenta de depuração, não a base de um scraper de produção.
Como uso um proxy autenticado com o Firefox no Selenium?
As preferências de perfil do Firefox configuram o endereço do proxy, mas não podem responder ao prompt de credenciais, e não há solução de extensão como no Chrome. Use lista branca de IPs para que nenhuma credencial seja necessária, ou roteie o Firefox através do selenium-wire, que lida com a autenticação upstream localmente.
Isso funciona da mesma forma em Java e C#?
Sim — a mecânica está no Chrome, não na ligação de linguagem. Lista branca de IPs mais --proxy-server é idêntico em todos os lugares, e a abordagem de extensão Manifest V3 funciona a partir de Java ou C# escrevendo os mesmos dois arquivos e adicionando --load-extension ao ChromeOptions. Apenas o selenium-wire é específico para Python; outras linguagens substituem por um proxy MITM local como o BrowserMob.
A versão curta: nunca lute contra a caixa de diálogo de autenticação. Liste quando seu IP for estável, gere uma extensão MV3 quando não for, mantenha o selenium-wire para trabalho de inspeção — e quando a manutenção do navegador superar os dados que produz, promova o trabalho para uma API e aproveite suas noites.