Entrar na lista
Todos os artigos
OAuthlocal developmentauthenticationcallbacks

Como testar callbacks de OAuth localmente

Para testar callbacks de OAuth localmente, você precisa de uma URL HTTPS pública que aponte para o seu app local. Os provedores de OAuth redirecionam o usuário de volta a uma URL de callback registrada após a autenticação — e a maioria exige HTTPS, algo que o localhost puro não consegue oferecer sem configuração extra.

Por que os redirect URIs de OAuth bloqueiam localhost

Os provedores de OAuth 2.0 validam o parâmetro redirect_uri contra uma lista branca de URLs registradas. Durante o desenvolvimento, seu callback pode ser assim:

https://your-app.portpreview.dev/auth/callback

Sem um túnel, você registra http://localhost:3000/auth/callback (permitido por alguns provedores, mas não por todos) ou faz deploy em staging a cada mudança de auth. Um túnel para localhost dá a você um endpoint HTTPS real na sua máquina.

O que você precisa para testar OAuth localmente

  • Credenciais do app OAuth (client ID e secret) do seu provedor.
  • Um app local com rotas de auth para iniciar o login e tratar o callback.
  • Uma URL de túnel registrada como redirect URI permitido no painel do provedor.
  • Variáveis de ambiente apontando para a URL do túnel durante o desenvolvimento.

Passo a passo: testar OAuth localmente com o PortPreview

  1. Inicie seu app localmente com as rotas de OAuth habilitadas.
  2. Execute npx portpreview 3000 para obter uma URL HTTPS pública.
  3. Adicione a URL de callback (por exemplo https://your-app.portpreview.dev/auth/callback) aos redirect URIs permitidos do seu provedor de OAuth.
  4. Atualize seu ambiente local para usar a URL do túnel como URL base.
  5. Inicie o fluxo OAuth no navegador e complete o ciclo de redirecionamento.
  6. Verifique a troca de tokens, a criação de sessão e o tratamento de erros.

Dicas por provedor

Google OAuth

O Google permite http://localhost para desenvolvimento, mas testar com túneis HTTPS valida o comportamento próximo ao de produção, incluindo flags de cookies seguros e políticas de conteúdo misto.

GitHub OAuth

O GitHub exige correspondência exata do redirect URI. Registre sua URL de túnel nas configurações do app OAuth e atualize-a quando a sessão do túnel mudar, ou use um subdomínio estável se o seu provedor de túnel oferecer suporte.

Auth0 e IdPs corporativos

Provedores de identidade corporativos costumam exigir callbacks HTTPS e às vezes restringem o localhost por completo. Túneis são a solução padrão para testes locais de integração SAML e OIDC.

Erros comuns ao testar OAuth localmente

  • Redirect URI sem correspondência: a URL de callback deve coincidir exatamente, incluindo barras finais e maiúsculas/minúsculas do path.
  • URL de túnel desatualizada: se a URL do túnel mudar entre sessões, atualize a lista branca do provedor.
  • Parâmetro state não validado: sempre verifique o parâmetro state para prevenir ataques CSRF, mesmo em desenvolvimento.
  • Problemas de domínio de cookie: cookies de sessão podem não persistir se as configurações de domínio conflitarem com o hostname do túnel.

Considerações de segurança

Callbacks de OAuth carregam códigos de autorização que devem ser trocados no servidor. Nunca exponha client secrets no código frontend e trate URLs de túnel como endpoints de desenvolvimento temporários, não como domínios de produção. Leia nosso guia de segurança de túneis para localhost para conhecer as melhores práticas.

Compartilhe fluxos de OAuth com o time

Quando produto ou QA precisarem testar login social, compartilhe a URL do túnel em vez de fazer deploy em staging. Veja como compartilhar seu servidor de desenvolvimento local para fluxos de colaboração.

Entre na lista de espera do PortPreview para agilizar os testes de OAuth e webhooks a partir de um único túnel.

Perguntas frequentes

Dá para testar OAuth no localhost?
Sim. A maioria dos provedores de OAuth permite redirect URIs http://localhost, mas muitos exigem HTTPS para testes próximos da produção. Um túnel para localhost oferece uma URL HTTPS pública mapeada para o seu app local.
Por que os provedores de OAuth exigem redirect URIs HTTPS?
O HTTPS protege os códigos de autorização e os tokens em trânsito durante o redirecionamento. Muitos provedores impõem HTTPS para evitar a interceptação de credenciais sensíveis em redes não seguras.
Como registro uma URL de túnel como redirect URI de OAuth?
Copie a URL HTTPS do túnel, acrescente o caminho do callback e adicione a URL completa à lista de redirect URIs permitidos no painel de desenvolvedor do seu provedor.