Tutoriais de VPS
Erros CORS no Nginx: preflight, cabeçalhos e login com cookies
Identifique OPTIONS ou requisição real com erro, escolha um responsável CORS e origem exata e confira erros, credenciais e login no navegador.

A API retorna JSON com curl, mas o navegador mostra blocked by CORS policy. Comece em Network: veja se falhou OPTIONS ou a requisição real seguinte e confira a resposta. Trocar de servidor ou colocar asteriscos não identifica a camada responsável.
O exemplo separa frontend https://app.example.com e API https://api.example.com. Permite somente uma origem explícita; adapte domínios, caminhos e porta do backend.
A documentação da MDN explica como o navegador controla a leitura de respostas por scripts de outra origem. Protocolo, hostname ou porta diferentes podem mudar a origem, inclusive entre subdomínios.
Uma resposta no curl não comprova que JavaScript pode lê-la. Erro 502, certificado inválido ou falha de conexão exigem corrigir a causa correspondente; cabeçalhos sozinhos não resolvem.
| Sintoma | O que conferir | Camada responsável |
|---|---|---|
| OPTIONS com 401/403 | Autenticação ou WAF bloqueia preflight | Gateway ou middleware |
| OPTIONS com 301/302 | HTTPS, barra final ou login | URL e regras do proxy |
| Falta Allow-Origin | A camada da resposta não o adiciona | Aplicação, Nginx ou CDN |
| Vários Allow-Origin | Duas camadas duplicam cabeçalhos | Escolher uma responsável |
| Falha com Cookie | Origem curinga ou credenciais | Frontend e servidor |
| Só erros da API parecem CORS | Resposta de erro sem cabeçalhos | Tratamento de erros |
Registre Request URL, Origin, status e cabeçalhos. Oculte Cookie e Authorization antes de compartilhar. Mantenha autenticação e proteção CSRF: CORS não impede chamadas diretas pelo curl.
POST JSON ou Authorization geralmente provoca preflight. O navegador consulta origem, método e cabeçalhos antes da requisição real; veja a referência. Simule no terminal:
curl -i -X OPTIONS 'https://api.example.com/api/profile' \
-H 'Origin: https://app.example.com' \
-H 'Access-Control-Request-Method: POST' \
-H 'Access-Control-Request-Headers: authorization,content-type'
Não precisa de token real nem Cookie. Confira:
Access-Control-Allow-Origincorresponde à origem completa do frontend.Access-Control-Allow-Methodsinclui POST.Access-Control-Allow-Headersinclui os cabeçalhos reais.
204 é comum, mas exige cabeçalhos compatíveis. Timeout maior não corrige 403 e adicionar Allow: OPTIONS não completa a autorização CORS. Confira também a resposta do POST real.
Se a URL redireciona para HTTP, login ou outro domínio, use a URL final diretamente. Veja ciclos de redirecionamento.
Escolha quem gerencia CORS. Se o framework tem middleware, use-o e elimine duplicatas no Nginx, painel e CDN. A alternativa abaixo deixa /api/ com o Nginx, mantendo autenticação no backend.
Integre o location ao servidor HTTPS existente da API. Preserve certificados e outros ajustes. O backend deve escutar em 127.0.0.1:3000 e precisar do caminho /api/:
location /api/ {
proxy_hide_header Access-Control-Allow-Origin;
proxy_hide_header Access-Control-Allow-Methods;
proxy_hide_header Access-Control-Allow-Headers;
proxy_hide_header Access-Control-Allow-Credentials;
add_header Access-Control-Allow-Origin "https://app.example.com" always;
add_header Access-Control-Allow-Methods "GET, POST, OPTIONS" always;
add_header Access-Control-Allow-Headers "Authorization, Content-Type" always;
if ($request_method = OPTIONS) {
return 204;
}
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_pass http://127.0.0.1:3000;
}
Limites do exemplo:
- Origem não tem caminho nem barra final.
http://localhost:5173de desenvolvimento é outra origem; confira origem não correspondente. - Permita só métodos e cabeçalhos necessários. Adicione PATCH, DELETE e campos personalizados quando preciso. Isso não substitui a validação do backend.
- Nginx responde OPTIONS e encaminha requisições normais. Se OPTIONS tem função de negócio, a aplicação deve distinguir os casos.
proxy_passnão tem barra final e preserva/api/. Não altere o mapeamento ao corrigir CORS.
A referência de cabeçalhos explica always, que também inclui cabeçalhos em erros. Sem isso, JavaScript pode não conseguir ler o 401 ou 500 real.
Confira a herança de add_header: definir cabeçalhos neste nível pode afetar os de segurança herdados. Examine a saída final. proxy_hide_header remove cabeçalhos upstream neste exemplo gerenciado pelo Nginx; não copie essa remoção quando a aplicação gerencia CORS.
Valide a sintaxe antes de carregar:
sudo nginx -t
sudo systemctl reload nginx
Uma CDN, WAF ou gateway anterior pode bloquear OPTIONS antes de chegar aqui. Permita preflight válido apenas nos caminhos necessários e continue autenticando requisições reais.
Para cookies entre origens, o frontend geralmente precisa explicitar credenciais:
fetch("https://api.example.com/api/profile", {
credentials: "include"
});
O servidor precisa de origem específica e Access-Control-Allow-Credentials: true. Na solução Nginx, adicione junto de add_header no mesmo location:
add_header Access-Control-Allow-Credentials "true" always;
Não combina com Access-Control-Allow-Origin: *, conforme a explicação da MDN. Não habilite credenciais em APIs que não precisam delas.
Enviar cookies também depende de Domain, Path, Secure, SameSite e políticas de terceiros. Entre origens não significa sempre entre sites: dois subdomínios não exigem automaticamente SameSite=None. Cookies realmente entre sites envolvem Secure e restrições do navegador. Se CORS funciona e login não, confira cookies e sessões em vez de ampliar origens.
mode: "no-cors" não permite ler a API entre origens. Gera resposta opaque sem acesso normal a status e JSON; veja Fetch.
Não reflita qualquer Origin com credenciais. Vários frontends confiáveis exigem lista exata. Ao escolher origem dinamicamente, configure Vary: Origin para separar respostas no cache.
Não adicione Allow-Origin simultaneamente na aplicação, Nginx e CDN. Duplicatas ou lista separada por vírgulas não autorizam várias origens, conforme a MDN. Confira a resposta final.
Teste OPTIONS e requisição real da origem permitida e depois uma origem diferente. Neste valor fixo, preflight não permitido pode retornar 204, mas Allow-Origin não coincide e o navegador não libera a leitura. Não é uma política de rejeição 403 no servidor.
Confira resposta sem login e erro controlado para confirmar uma configuração CORS só. Depois teste login e ação reais no navegador. curl observa cabeçalhos sem aplicar políticas de CORS, cookies ou cache.
O artigo original testou oito combinações com Nginx 1.19.6 e backend simulado em loopback. OPTIONS permitido retornou 204 e GET/POST 200; respostas 401 e 500 mantiveram um Allow-Origin. Origens diferentes não coincidiam. Com credenciais, OPTIONS e GET incluíam true. OPTIONS não chegou ao backend. Foram verificações de cabeçalhos HTTP, sem TLS de produção, sessão real ou bloqueio efetivo do navegador.
Para FastAPI, veja implantação e CORS. Identifique a requisição com erro e uma camada responsável pelos cabeçalhos antes de alterar regras.