Como usar proxies residenciais no Selenium (incluindo proxies autenticados)

O Selenium define o host do proxy facilmente, mas não tem uma forma nativa de passar credenciais. Como lidar com proxies autenticados usando Selenium Wire, uma extensão, ou CDP.

O Selenium é a ferramenta de automação de navegador mais amplamente utilizada que existe, e para fazer scraping de um alvo com muito JavaScript ele cumpre a função. Mas ele tem uma lacuna antiga que pega quase todo mundo na primeira vez que adicionam um proxy residencial: configurar o host do proxy é trivial, e fornecer um usuário e senha não é, porque o Selenium não tem uma forma nativa de fazer isso. Aponte o Chrome para um proxy autenticado e ele abre uma janela de login nativa 407 que o Selenium não consegue preencher, e seu script trava. Veja aqui como contornar isso, de três formas.

Isso se soma aos outros guias de navegador, proxies residenciais com Playwright e no Puppeteer, ambos lidam com autenticação de proxy nativamente. Se você não precisa de um navegador completo, proxies em Python com um cliente HTTP simples é ainda mais fácil.

Tudo abaixo usa o gateway residencial da Shifter: um único endpoint, p.shifter.io:443, com toda a segmentação codificada no nome de usuário. Troque o host e as credenciais por outro provedor; a estrutura é a mesma.

O modelo de gateway em um parágrafo

O nome de usuário do proxy carrega sua autenticação e sua segmentação. Você não troca de endpoint para mudar o país ou a sessão, você muda a string do nome de usuário:

customer-USERNAME-country-us-sid-abc123-ttl-600

country-us direciona para os Estados Unidos, sid fixa uma sessão persistente, ttl mantém aquele IP por N segundos. Omita sid/ttl e cada nova conexão faz rotação. A senha permanece constante. Todo o problema no Selenium é fazer esse nome de usuário e senha chegarem ao proxy.

O problema central

Configurar o host é a metade fácil. Você passa --proxy-server nas opções do Chrome exatamente como faria em qualquer outro lugar:

from selenium import webdriver

options = webdriver.ChromeOptions()
options.add_argument('--proxy-server=http://p.shifter.io:443')   # host only
driver = webdriver.Chrome(options=options)

Isso funciona para um proxy com whitelist de IP sem credenciais. Mas o gateway é autenticado por usuário e senha, e o Chromium não vai ler credenciais dessa flag, então a primeira navegação trava em um prompt de autenticação 407 que o Selenium não consegue dispensar. Você precisa de uma de três formas para responder a esse desafio.

Abordagem 1: Selenium Wire (a mais fácil)

O Selenium Wire estende o Selenium e aceita credenciais de proxy diretamente, lidando com a autenticação para você. É a opção com menos atrito e a que a maioria dos scrapers em Python usa.

from seleniumwire import webdriver   # pip install selenium-wire
import os

user = os.environ['SHIFTER_USER'] + '-country-us'   # targeting in the username
pw = os.environ['SHIFTER_PASS']

seleniumwire_options = {
    'proxy': {
        'http':  f'http://{user}:{pw}@p.shifter.io:443',
        'https': f'http://{user}:{pw}@p.shifter.io:443',
        'no_proxy': 'localhost,127.0.0.1',
    }
}

driver = webdriver.Chrome(seleniumwire_options=seleniumwire_options)
driver.get('https://api.ipify.org')
print(driver.page_source)   # a US residential IP
driver.quit()

As credenciais, incluindo as flags de segmentação no nome de usuário, vão na configuração proxy e o Selenium Wire lida com o 407 de forma transparente. Ele também permite trocar o proxy em tempo de execução reatribuindo driver.proxy, o que é útil para rotação sem relançar o Chrome.

Abordagem 2: uma extensão de credenciais (Selenium puro, sem biblioteca extra)

Se você quiser continuar no Selenium puro, a técnica clássica é carregar uma pequena extensão do Chrome que responde ao desafio de autenticação com suas credenciais. Você a constrói na hora e a passa com add_extension.

# manifest.json declares proxy + auth permissions; background.js supplies creds.
background_js = """
chrome.webRequest.onAuthRequired.addListener(
  () => ({ authCredentials: { username: USER, password: PASS } }),
  { urls: ['<all_urls>'] },
  ['blocking']
);
""".replace('USER', repr(user)).replace('PASS', repr(pw))
# zip manifest.json + background.js, then:
options.add_extension('proxy_auth.zip')

Isso mantém você livre de dependências e funciona em qualquer binding de linguagem do Selenium, já que a extensão faz o trabalho. A ressalva: o padrão bloqueante onAuthRequired acima é uma técnica de Manifest V2, e o Chrome está eliminando gradualmente o MV2 em favor do MV3, então no Chrome atual essa abordagem é mais frágil do que costumava ser. Se você está começando do zero, prefira o Selenium Wire ou a rota de CDP abaixo.

Abordagem 3: CDP no Selenium 4

O Selenium 4 expõe o Chrome DevTools Protocol, e você pode responder à autenticação do proxy através do domínio Fetch, tratando Fetch.authRequired e continuando a requisição com credenciais. É nativo do Selenium moderno e não precisa de pacote extra, mas é complicado de configurar manualmente, essencialmente reimplementando o que o Selenium Wire já encapsula. Recorra a isso quando você quiser zero dependências de terceiros e estiver confortável com CDP; caso contrário, o Selenium Wire poupa o trabalho.

Rotacionando geo e sessões

Como a segmentação vive no nome de usuário, uma identidade diferente é um nome de usuário diferente, e no Selenium o proxy é configurado no nível do navegador. Isso significa que a rotação acontece por driver, não por aba. Dois padrões práticos: com o Selenium Wire, reatribua driver.proxy em tempo de execução para trocar o nome de usuário entre unidades de trabalho; com a abordagem de extensão ou CDP, rode um driver por identidade e agrupe-os em um pool. De qualquer forma, dê a cada unidade lógica de trabalho seu próprio sid e rotacione entre unidades, não no meio da sessão (sticky vs rotating cobre essa distinção), e mapeie o trabalho para identidades como descrito no post sobre balanceamento de carga.

Reutilize o driver e limite a concorrência

Lançar o Chrome é caro, um driver novo por requisição paga um custo real de inicialização e memória toda vez, a sobrecarga que o guia de latência existe para eliminar. Inicie um driver (ou um pequeno pool deles) e reutilize-o entre requisições. E como cada driver é um navegador completo ocupando memória real, você não pode rodar milhares, mantenha um pool limitado e limite o trabalho em andamento por host alvo para que um site frágil não seja sobrecarregado enquanto um permissivo fica sem uso. Mais paralelismo além da tolerância de um alvo só traz bloqueios e falhas por falta de memória, não throughput (como evitar ser bloqueado).

O navegador é só metade de não ser bloqueado

Um IP residencial cuida da metade de rede de parecer humano, mas o Selenium ainda está controlando um navegador automatizado, e os sites também fazem fingerprint disso, navigator.webdriver, flags de automação, e peculiaridades do modo headless. Um IP limpo com boa reputação evita muitos desafios, mas não disfarça um navegador claramente automatizado. Mantenha o user-agent e o viewport realistas, conduza a página em um ritmo humano, e lembre-se de que os erros que disparam detecção se aplicam à camada do navegador tanto quanto à camada de IP. As duas precisam estar alinhadas.

Verifique se você está realmente no proxy

Antes de fazer benchmark ou depurar qualquer outra coisa, confirme o IP de saída de dentro do navegador:

driver.get('http://ip-api.com/json')
print(driver.find_element('tag name', 'body').text)   # expect the targeted country

Seu próprio IP significa que o proxy não está aplicado. Uma travada em uma janela de login significa que a etapa de autenticação (Selenium Wire, extensão ou CDP) está ausente ou mal configurada. Uma travada geral significa que a saída local está bloqueada. Os três casos são cobertos no guia de diagnóstico de timeout.

Perguntas frequentes

Por que o Selenium trava em um popup de login do proxy? O Chromium levanta uma janela de autenticação nativa 407 para um proxy autenticado, e o Selenium não consegue interagir com janelas nativas do navegador. Você precisa responder ao desafio de outra forma: Selenium Wire, uma extensão de credenciais, ou Fetch.authRequired do CDP. Configurar apenas --proxy-server fornece só o host, não as credenciais.

Posso colocar user:pass@host em --proxy-server? Não. O Chromium não lê credenciais da flag --proxy-server. Forneça o host ali e passe o usuário e a senha através de uma das três abordagens acima. Como o gateway codifica a segmentação no nome de usuário, o nome de usuário completo (com -country-...) é o que você passa como usuário do proxy.

Preciso usar o Selenium Wire? Não, mas é o caminho mais simples em Python. As alternativas sem dependências são uma extensão de credenciais (funciona em qualquer binding de linguagem, embora o padrão clássico MV2 esteja sendo eliminado gradualmente) ou CDP no Selenium 4 (nativo, mas mais trabalhoso de configurar).

Como faço rotação de IPs no Selenium? Varie o nome de usuário do proxy, o que muda a identidade através do mesmo gateway. No Selenium Wire você pode reatribuir driver.proxy em tempo de execução; caso contrário, rode um driver por identidade e agrupe-os em um pool. Omita o sid no nome de usuário para rotacionar a cada nova conexão.

Selenium, Playwright, ou Puppeteer? Playwright e Puppeteer aceitam credenciais de proxy nativamente, então evitam toda essa complicação; o Selenium precisa de uma das soluções alternativas aqui. O Selenium ainda é uma boa escolha se já for o que sua stack usa; se você está começando do zero e quer autenticação de proxy sem dor de cabeça, os outros dois são mais tranquilos.

Conclusão

Selenium com proxies residenciais funciona bem assim que você resolve a única lacuna que ele tem: ele aceita o host do proxy em --proxy-server, mas precisa de ajuda para fornecer credenciais para um proxy autenticado. Use o Selenium Wire para o menor atrito, uma extensão de credenciais se você quiser continuar sem dependências, ou CDP no Selenium 4 para uma rota nativa. Depois rotacione geo e sessões variando o nome de usuário, reutilize um driver de vida longa, limite sua concorrência porque cada um é um navegador real, e mantenha o fingerprint do navegador tão humano quanto o IP.

Acerte isso e o Selenium lida com os alvos interativos e ricos em JavaScript que clientes HTTP simples não conseguem. Aponte-o para o gateway residencial, e lembre-se de que a qualidade do pool determina com que frequência você é desafiado (reputação de IP). A página de preços tem os planos por GB para testar contra seus próprios alvos.