Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Gerir Autenticação e Sessões

Aula 8 de 14 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. O Desafio da Autenticação
  2. Login Baseado em Formulário
  3. Reutilizar o Estado da Sessão
  4. Gerir a Autenticação de Dois Fatores (2FA)
  5. Gerir o SSO (Single Sign-On)
  6. Detetar o Estado de Login
  7. Segurança das Credenciais
  8. Pontos-chave

Lição reescrita a 3 de novembro de 2026 com base no guia Computer use da OpenAI e na documentação de autenticação do Playwright. A versão anterior colocava palavras-passe e códigos 2FA diretamente no prompt enviado ao modelo — inclusive através de variáveis de ambiente, o que não impede a sua transmissão — e delegava o login SSO ao agente. Agora, o seu código gere os segredos, o estado da sessão é guardado usando storage_state e o SSO é efetuado uma única vez manualmente. Fontes: Computer use · Playwright, authentication.

O Desafio da Autenticação

A maioria dos fluxos de automação exige estar autenticado num serviço. Enquanto o seu agente permanecer em páginas públicas, tudo funciona bem; no momento em que precisa de abrir um CRM, um back-office ou uma caixa de entrada de e-mail, depara-se com uma barreira de login. Formulários, 2FA, SSO e sessões persistentes exigem cada um um tratamento diferente, mas uma regra governa-os a todos: o modelo nunca vê um segredo.

Login Baseado em Formulário

A tentação é ditar a sequência ao agente, incluindo as credenciais:

# NÃO FAÇA ISTO: a palavra-passe vai para o pedido enviado à API
task = """
Inicie sessão no site:
1. Clique no campo de e-mail e escreva: [email protected]
2. Clique no campo de palavra-passe e escreva: MyPassword123
3. Clique no botão "Log in"
"""

Ler a palavra-passe de uma variável de ambiente antes de a inserir no prompt não muda nada: continua a deixar a sua infraestrutura no pedido, é retida com a resposta — as respostas são guardadas por defeito (Lição 12) — e pode vazar para os seus registos (logs). A OpenAI recomenda manter as credenciais fora do texto da página e das capturas de ecrã. A solução é fazer com que o seu código preencha o formulário de login com o Playwright e só depois entregue o controlo ao agente assim que a sessão estiver aberta.

import os

def log_in(page, login_url: str):
    """Login efetuado pelo seu código: o modelo nunca vê a palavra-passe."""
    page.goto(login_url)
    page.get_by_label("Email").fill(os.environ["APP_EMAIL"])
    page.get_by_label("Password").fill(os.environ["APP_PASSWORD"])
    page.get_by_role("button", name="Log in").click()
    page.wait_for_load_state("networkidle")

Adapte os rótulos Email e Password à sua aplicação. Este é um dos poucos locais no fluxo de trabalho onde um seletor é totalmente justificado: uma página de login raramente muda e as questões de segurança superam a flexibilidade.

Reutilizar o Estado da Sessão

Fazer login em cada execução desperdiça tempo e pode, por vezes, desencadear alertas de segurança no lado do serviço. O Playwright pode guardar o estado de um contexto — cookies, armazenamento local, IndexedDB — num ficheiro e, em seguida, criar um novo contexto a partir desse ficheiro.

import os

def save_session(context, filepath="session.json"):
    """Guarda o estado atual da sessão."""
    context.storage_state(path=filepath)

def new_context_with_session(browser, filepath="session.json"):
    """Cria um contexto a partir de uma sessão guardada, se existir."""
    options = {"viewport": {"width": 1280, "height": 720}}
    if os.path.exists(filepath):
        options["storage_state"] = filepath
    return browser.new_context(**options)

Integrado no fluxo de trabalho, isto cria uma lógica de dois passos: começar a partir da sessão guardada, verificar se ainda é válida e só voltar a fazer login se isso falhar. O estado é guardado novamente após a tarefa, porque muitos serviços renovam o seu token de sessão ao longo do processo.

from playwright.sync_api import sync_playwright

def authenticated_workflow(task: str, login_url: str):
    """Fluxo de trabalho com reutilização de sessão."""
    pw = sync_playwright().start()
    browser = pw.chromium.launch(headless=True)
    try:
        context = new_context_with_session(browser)
        page = context.new_page()
        page.goto(login_url)

        if is_logged_in(page):
            print("Sessão restaurada com sucesso")
        else:
            log_in(page, login_url)  # o seu código, não o do agente
            if not is_logged_in(page):
                raise RuntimeError("Login impossível: verifique as credenciais ou o 2FA")
        save_session(context)

        result = run_agent(task, page=page)
        save_session(context)  # atualizar estado
        return result
    finally:
        browser.close()
        pw.stop()

Trate o ficheiro de sessão como uma palavra-passe: o Playwright avisa que pode conter cookies e cabeçalhos que permitem a personificação de contas e desaconselha vivamente o seu controlo de versões, mesmo num repositório privado. Guarde-o juntamente com os seus segredos.

Gerir a Autenticação de Dois Fatores (2FA)

O 2FA representa um desafio porque frequentemente requer intervenção humana, seja um código SMS ou uma aplicação de autenticação. É exatamente esse o seu propósito: foi concebido para que um autómato não o possa contornar sozinho. Coexistem duas abordagens dependendo do fator utilizado, e a escolha do fator aquando da criação da conta de serviço determina se o seu fluxo de trabalho pode ser executado sem supervisão.

TOTP Automatizado

Se a conta utilizar uma aplicação TOTP como o Google Authenticator ou o Authy, o código apresentado é apenas uma função do segredo partilhado e do relógio. O seu código pode, portanto, geri-lo e introduzi-lo ele próprio, sem o mostrar ao modelo.

import os

import pyotp

def enter_totp_code(page):
    """Introduz o código TOTP atual: o segredo e o código permanecem no seu código."""
    totp = pyotp.TOTP(os.environ["TOTP_SECRET"])
    page.get_by_label("Verification code").fill(totp.now())
    page.get_by_role("button", name="Verify").click()

Pense no que está a fazer: armazenar o segredo TOTP juntamente com a palavra-passe reduz o 2FA a um único fator, uma vez que ambos os segredos residem no mesmo local. Reserve esta abordagem para uma conta de serviço dedicada, com direitos limitados ao estritamente necessário.

Espera Manual

Fatores não automatizáveis, como SMS ou notificações push, exigem uma pausa explícita. O agente para, um operador valida no seu telemóvel e, em seguida, o ciclo retoma onde tinha parado. Esta é uma solução aceitável para um processo lançado manualmente, muito menos para uma tarefa cron noturna.

def wait_for_2fa(page):
    """Pausa o agente e aguarda validação manual."""
    print("2FA necessário. Valide manualmente e, em seguida, prima Enter.")
    input("Prima Enter para continuar...")
    # O agente retoma após a validação

Gerir o SSO (Single Sign-On)

Os logins SSO (Google, Microsoft, SAML) redirecionam para um fornecedor de identidade externo: o agente mudaria de domínio a meio do fluxo e teria de introduzir credenciais lá. Não delegue este passo ao agente. Efetue o login SSO uma vez, manualmente, num navegador visível controlado pelo Playwright e, em seguida, guarde o estado da sessão: as execuções subsequentes partem deste estado.

def manual_sso_login(login_url: str, filepath="session.json"):
    """Um humano faz login num navegador visível; a sessão é guardada."""
    pw = sync_playwright().start()
    browser = pw.chromium.launch(headless=False)
    context = browser.new_context()
    page = context.new_page()
    page.goto(login_url)
    input("Faça login na janela aberta e, em seguida, prima Enter...")
    save_session(context, filepath)
    browser.close()
    pw.stop()

Quando a sessão expirar eventualmente, o fluxo de trabalho deve parar e solicitar novamente este login humano. Adicione esta instrução às diretrizes do agente: se se encontrar perante uma página de um fornecedor de identidade, deve parar e reportá-lo em vez de tentar qualquer coisa.

Detetar o Estado de Login

Toda esta mecânica assenta numa questão à qual deve ser capaz de responder de forma fiável: estamos autenticados? Uma função dedicada cruza dois sinais: primeiro o URL atual, uma vez que um redirecionamento para /login é inequívoco; depois a presença de um elemento reservado a utilizadores autenticados, tipicamente o menu da conta. O primeiro teste é instantâneo, o segundo cobre aplicações que apresentam a página de login sem alterar o URL.

from playwright.sync_api import TimeoutError as PlaywrightTimeoutError

def is_logged_in(page) -> bool:
    """Verifica se a sessão está ativa."""
    # Verificação do URL
    if "/login" in page.url or "/signin" in page.url:
        return False

    # Verificação do elemento DOM
    try:
        page.wait_for_selector("[data-testid=user-menu]", timeout=3000)
        return True
    except PlaywrightTimeoutError:
        return False

O except visa precisamente a expiração do tempo limite: um except: simples também engoliria uma interrupção de teclado ou um erro de programação real, o que você quer ver propagar-se.

Segurança das Credenciais

"Nunca guarde palavras-passe no seu código-fonte, nos seus prompts ou nos seus registos."

— Regra fundamental de segurança

Na prática, esta regra desdobra-se em alguns hábitos que quase não têm custo uma vez adotados. As credenciais vivem em variáveis de ambiente, alimentadas em desenvolvimento por um ficheiro .env que exclui imediatamente do controlo de versões via .gitignore — esta omissão é uma causa clássica de fugas de segredos em repositórios públicos. Em produção, substitua este ficheiro por um gestor de segredos, como o Vault ou o AWS Secrets Manager, que fornece valores a pedido e regista o acesso. Apenas o seu código os lê, nunca o modelo. Preveja a rotação regular de palavras-passe e tokens de API, para que uma fuga antiga já não abra nada. Por fim, filtre os seus registos para nunca gravar dados sensíveis neles: um agente que regista fielmente cada tecla pressionada também copia aquilo que foi mandado escrever.

Pontos-chave

  • O modelo nunca vê um segredo: o seu código introduz a palavra-passe e o código 2FA com o Playwright
  • Guarde o estado da sessão com storage_state e trate esse ficheiro como um segredo
  • O TOTP é automatizado no lado do código, reservado para uma conta de serviço com direitos limitados
  • Efetue o login SSO uma vez manualmente e, em seguida, reutilize a sessão guardada
  • Verifique sempre o estado de login antes de lançar um fluxo de trabalho