Marcio Cunha

Como resolver erros de CORS em APIs com Proxy Reverso

Aprenda na prática como eliminar os temidos bloqueios de CORS configurando cabeçalhos HTTP no Nginx para liberar sua API com segurança.

Marcio Cunha•6 min
Também disponível em:EnglishEspañol
Resumo
  • O CORS é um mecanismo de segurança dos navegadores que impede páginas web de acessarem recursos de domínios diferentes sem permissão expressa.
  • O proxy reverso atua como intermediário e permite injetar os cabeçalhos de liberação antes que o navegador barre a resposta do servidor.
  • A requisição preliminar chamada de preflight usa o método OPTIONS e precisa ser tratada corretamente pelo servidor para validar as permissões.
  • Cabeçalhos como Access-Control-Allow-Origin controlam exatamente quais endereços externos ganham passe livre para consultar a API.
  • Configurações mal planejadas no proxy podem expor dados sensíveis ou falhar ao lidar com credenciais e cookies de autenticação.

O que é o CORS e por que ele bloqueia suas requisições

Quem nunca esbarrou em uma mensagem vermelha no console do navegador dizendo que a política de mesma origem bloqueou o acesso à API? Na prática, o CORS (Cross-Origin Resource Sharing, ou compartilhamento de recursos entre origens diferentes) funciona como um segurança severo na porta de uma festa exclusiva. Quando um site tenta buscar dados de um servidor hospedado em um endereço diferente, o navegador assume uma postura defensiva e barra a comunicação para evitar ataques maliciosos de roubo de sessão.

Isso acontece porque a web foi construída sob o princípio de isolamento de origens. Se você entra em um site duvidoso, o navegador impede que esse site faça chamadas silenciosas para o seu banco ou para a API da sua empresa usando as suas credenciais salvas. No entanto, em arquiteturas modernas onde o frontend corre em um servidor separado do backend, esse mecanismo de proteção muitas vezes atrapalha o desenvolvimento legítimo. É justamente aí que entra a necessidade de dominar ferramentas como o Nginx para ajustar as regras do jogo.

Para entender o problema a fundo, vale lembrar como inspecionamos o comportamento de rede em ferramentas do dia a dia, algo comparável à facilidade de como inspecionar tráfego HTTP com curl no terminal quando precisamos debugar conexões puras sem a interferência visual do navegador. Quando o bloqueio ocorre, o navegador não esconde o motivo: ele exige que o servidor envie sinais claros dizendo que aquela origem específica é confiável e tem autorização para ler o conteúdo da resposta.

Como o proxy reverso resolve o problema na raiz

Resolver o CORS diretamente no código da aplicação pode ser trabalhoso, especialmente se você gerencia dezenas de microsserviços escritos em linguagens diferentes. A abordagem mais elegante e profissional consiste em delegar essa responsabilidade para o proxy reverso, como o Nginx, que fica na frente de toda a infraestrutura. Na prática, o proxy reverso intercepta a requisição do cliente antes que ela chegue ao código principal e injeta os cabeçalhos HTTP necessários para acalmar o navegador.

Essa centralização traz uma vantagem operacional gigantesca. Em vez de alterar o código em Node.js, Python ou Go toda vez que uma nova URL de homologação ou produção for liberada, você ajusta apenas um arquivo de configuração central. Além disso, o proxy lida com requisições complexas de forma unificada, garantindo que o comportamento de segurança seja consistente em toda a arquitetura de software, mantendo os servidores de backend focados apenas na regra de negócio.

A lógica de funcionamento do proxy se assemelha à organização de sistemas complexos, onde cada camada tem uma função bem definida para evitar gargalos, similar aos conceitos que exploramos quando discutimos por que gRPC e Protocol Buffers são mais rápidas que JSON em termos de eficiência de comunicação e transporte de dados entre serviços distribuídos. No caso do CORS, o proxy atua como um tradutor diplomático que negocia as permissões antes de entregar o dado sensível ao cliente final.

Configurando os cabeçalhos HTTP essenciais no Nginx

Para destravar o acesso no Nginx, precisamos configurar cabeçalhos específicos que dizem ao navegador quais origens, métodos e credenciais são aceitos. O cabeçalho mais importante é o Access-Control-Allow-Origin, que define quem tem permissão para consumir os dados. Em ambientes abertos, podemos usar um asterisco para liberar geral, mas em APIs corporativas o ideal é mapear dinamicamente a origem da requisição.

Outro ponto crítico são os métodos HTTP permitidos, controlados pelo cabeçalho Access-Control-Allow-Methods, que especifica se o cliente pode enviar requisições do tipo GET, POST, PUT, DELETE ou OPTIONS. Quando o cliente envia cabeçalhos personalizados, como um token de autenticação no campo Authorization, também precisamos explicitá-los no cabeçalho Access-Control-Allow-Headers para evitar que o navegador descarte a resposta no meio do caminho.

Abaixo temos um bloco de configuração funcional para aplicar diretamente no seu bloco server ou location do Nginx:

location /api/ {
if ($request_method = 'OPTIONS') {
add_header 'Access-Control-Allow-Origin' 'https://meusite.com' always;
add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE' always;
add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type' always;
add_header 'Access-Control-Max-Age' 1728000;
add_header 'Content-Type' 'text/plain charset=UTF-8';
add_header 'Content-Length' 0;
return 204;
}

add_header 'Access-Control-Allow-Origin' 'https://meusite.com' always;
add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE' always;
add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type' always;
proxy_pass http://backend_upstream;
}

Entendendo o papel da requisição Preflight

Muitas pessoas se confundem porque o Nginx precisa lidar com um método HTTP chamado OPTIONS antes mesmo da requisição principal acontecer. Esse processo é conhecido como requisição de verificação prévia, ou preflight. Sempre que o navegador percebe que a chamada possui cabeçalhos customizados ou métodos não padrões, ele envia um tiro no escuro usando o método OPTIONS para perguntar ao servidor se a operação real é permitida.

Se o servidor não responder corretamente a essa chamada OPTIONS com os cabeçalhos de CORS adequados, o navegador cancela imediatamente a requisição real de dados, gerando o famoso erro de CORS que frustra muitos desenvolvedores iniciantes. É por isso que no bloco de configuração anterior tratamos explicitamente o método OPTIONS, retornando um código de status 204 indicando que a operação foi compreendida e aprovada sem a necessidade de processamento pesado no backend.

O uso do Access-Control-Max-Age dentro dessa verificação prévia serve para cachear a resposta do preflight por um determinado período em segundos, evitando que o navegador envie uma requisição OPTIONS repetida a cada clique do usuário na interface, o que otimiza consideravelmente a performance da aplicação web em cenários de alta interatividade.

Boas práticas e armadilhas comuns na configuração

Configurar CORS no proxy reverso exige cuidado para não abrir brechas de segurança indesejadas na infraestrutura. O uso indiscriminado do caractere coringa * no cabeçalho de origem parece prático, mas se a sua API lida com dados sensíveis ou sessões autenticadas por cookies, os navegadores modernos simplesmente proíbem o uso do asterisco em conjunto com o cabeçalho Access-Control-Allow-Credentials: true.

Outro erro frequente é duplicar os cabeçalhos de CORS. Se tanto a sua aplicação backend quanto o proxy Nginx injetarem o cabeçalho Access-Control-Allow-Origin ao mesmo tempo, o navegador receberá valores duplicados separados por vírgula e interpretará isso como uma falha de conformidade, mantendo o bloqueio ativo. A diretiva always no Nginx garante que o cabeçalho seja enviado mesmo quando o backend retorna códigos de erro como 400 ou 500, facilitando o diagnóstico de falhas no frontend.

Manter o rigor na especificação das origens confiáveis protege contra vazamentos de dados via requisições cruzadas não autorizadas, garantindo que apenas os domínios legítimos da sua empresa ou de parceiros homologados consigam interagir com os serviços expostos na borda da rede. Para aprofundar esses conceitos na prática em produção, confira também nossa análise técnica sobre Como consertar trilha rompida na placa com fio e solda.

Considerações finais

Dominar a resolução de erros de CORS através de um proxy reverso como o Nginx é uma habilidade indispensável para qualquer engenheiro que lida com arquiteturas web desacopladas. Ao transferir a responsabilidade de negociação de segurança para a camada de proxy, ganhamos flexibilidade operacional, centralizamos regras e evitamos alterações repetitivas no código-fonte das nossas aplicações.

Com uma configuração limpa, tratamento adequado das requisições de preflight e atenção redobrada aos cabeçalhos de credenciais, é possível construir ecossistemas de APIs robustos, seguros e totalmente livres de bloqueios indesejados no navegador, garantindo uma experiência fluida para os usuários finais da plataforma.