Back-end8 min de leitura

CORS Explicado: Como Proteger sua API de Invasores Web

Same-Origin Policy e CORS do zero: preflight requests, headers de resposta, whitelist com variáveis de ambiente, credenciais e cookies, e a relação com CSRF.

12 de agosto de 2026

O erro de CORS é um dos mais frustrantes para quem está começando no desenvolvimento web — não porque é difícil de corrigir, mas porque não é intuitivo de entender. O erro não vem do seu servidor, vem do navegador. E a solução mais comum que você vê no Stack Overflow — origin: '*' — funciona mas abre um buraco de segurança significativo.

Neste artigo vamos do mecanismo fundamental (Same-Origin Policy) até a configuração correta para produção: whitelist dinâmica, preflight requests, headers necessários, e a relação com cookies e CSRF.

Same-Origin Policy: A Raiz do Problema

O navegador implementa a Same-Origin Policy — uma regra de segurança que impede que JavaScript em https://site-pirata.com faça requisições para https://api.suaempresa.com. A origem é a combinação de protocolo + domínio + porta. Qualquer diferença em um desses três campos = origens diferentes = bloqueio por padrão.

https://app.com → https://app.com/api ✅ Mesma origem
https://app.com → https://api.app.com ❌ Subdomínio diferente
https://app.com → http://app.com ❌ Protocolo diferente
https://app.com → https://app.com:4000 ❌ Porta diferente
https://app.com → https://outro.com ❌ Domínio diferente

O CORS (Cross-Origin Resource Sharing) é o mecanismo pelo qual o servidor pode flexibilizar essa política, dizendo ao navegador: 'Eu autorizo requisições vindas da origem X'. Sem esse header, o navegador bloqueará a resposta antes de entregá-la ao JavaScript — mesmo que o servidor tenha processado e respondido.

CORS não protege o seu servidor — protege os usuários. O servidor processa a requisição normalmente. É o navegador que decide se entrega ou não a resposta ao JavaScript da página. Ferramentas como Postman e curl não são navegadores e por isso ignoram CORS completamente.

Preflight Requests: O que Acontece nos Bastidores

Para requisições que modificam dados (POST, PUT, DELETE) ou que enviam headers customizados (Authorization, Content-Type: application/json), o navegador faz uma preflight request automática antes da requisição real:

Navegador envia OPTIONS /api/users com headers Origin, Access-Control-Request-Method e Access-Control-Request-Headers
Servidor responde com Access-Control-Allow-Origin, Access-Control-Allow-Methods e Access-Control-Allow-Headers
Se a resposta autorizar, o navegador envia a requisição real (POST, PUT, etc.)
Se não autorizar, o navegador bloqueia e você vê o erro de CORS

Isso significa que em produção você terá o dobro de requisições para endpoints não-simples. O header Access-Control-Max-Age resolve isso cacheando o resultado do preflight:

Configuração Correta no Express

bash

1npm install cors
npm install cors
2npm install -D @types/cors
npm install -D @types/cors

cors.ts

1import type { CorsOptions } from 'cors';
import type { CorsOptions } from 'cors';
2

3// Lista de origens permitidas — carrega do ambiente
// Lista de origens permitidas — carrega do ambiente
4// Em produção: ALLOWED_ORIGINS=https://app.com,https://painel.app.com
// Em produção: ALLOWED_ORIGINS=https://app.com,https://painel.app.com
5const allowedOrigins = (
const allowedOrigins = (
6  process.env.ALLOWED_ORIGINS ?? 'http://localhost:3000'
  process.env.ALLOWED_ORIGINS ?? 'http://localhost:3000'
7)
)
8  .split(',')
  .split(',')
9  .map((origin) => origin.trim());
  .map((origin) => origin.trim());
10

11export const corsOptions: CorsOptions = {
export const corsOptions: CorsOptions = {
12  origin: (origin, callback) => {
  origin: (origin, callback) => {
13    // origin é undefined para:
    // origin é undefined para:
14    // - Requisições do mesmo domínio (raras)
    // - Requisições do mesmo domínio (raras)
15    // - Apps mobile, Postman, curl
    // - Apps mobile, Postman, curl
16    // - Webhooks de serviços externos
    // - Webhooks de serviços externos
17    // Permitimos essas, mas revise se sua API é puramente para browsers
    // Permitimos essas, mas revise se sua API é puramente para browsers
18    if (!origin) {
    if (!origin) {
19      callback(null, true);
      callback(null, true);
20      return;
      return;
21    }
    }
22

23    if (allowedOrigins.includes(origin)) {
    if (allowedOrigins.includes(origin)) {
24      callback(null, true);
      callback(null, true);
25    } else {
    } else {
26      callback(new Error(`Origem ${origin} não autorizada pelo CORS.`));
      callback(new Error(`Origem ${origin} não autorizada pelo CORS.`));
27    }
    }
28  },
  },
29

30  // OBRIGATÓRIO para cookies HttpOnly (Refresh Token) funcionarem
  // OBRIGATÓRIO para cookies HttpOnly (Refresh Token) funcionarem
31  credentials: true,
  credentials: true,
32

33  // Métodos HTTP permitidos
  // Métodos HTTP permitidos
34  methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
  methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
35

36  // Headers que o cliente pode enviar
  // Headers que o cliente pode enviar
37  allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With'],
  allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With'],
38

39  // Headers que o cliente pode ler na resposta
  // Headers que o cliente pode ler na resposta
40  exposedHeaders: ['X-Total-Count', 'X-Page'],
  exposedHeaders: ['X-Total-Count', 'X-Page'],
41

42  // Cache do preflight: 24 horas (reduz OPTIONS requests)
  // Cache do preflight: 24 horas (reduz OPTIONS requests)
43  maxAge: 86400,
  maxAge: 86400,
44};
};

server.ts

1import express from 'express';
import express from 'express';
2import cors from 'cors';
import cors from 'cors';
3import { corsOptions } from './config/cors';
import { corsOptions } from './config/cors';
4

5const app = express();
const app = express();
6

7// CORS deve vir ANTES de qualquer rota
// CORS deve vir ANTES de qualquer rota
8// O método OPTIONS do preflight precisa ser tratado globalmente
// O método OPTIONS do preflight precisa ser tratado globalmente
9app.use(cors(corsOptions));
app.use(cors(corsOptions));
10

11// Para preflight requests em todas as rotas:
// Para preflight requests em todas as rotas:
12app.options('*', cors(corsOptions));
app.options('*', cors(corsOptions));
13

14app.use(express.json());
app.use(express.json());
15// ... rotas
// ... rotas

CORS e Cookies: credentials: true

Se você usa cookies HttpOnly para o Refresh Token, há dois requisitos obrigatórios que muitos desenvolvedores esquecem:

No servidor: credentials: true na config do cors. Com credentials: true, o origin *não pode ser `''`** — precisa ser um domínio específico.
No cliente: withCredentials: true no Axios (ou credentials: 'include' no fetch). Sem isso, o navegador não envia nem recebe cookies cross-origin.

Configuração do cliente (Axios)

1// Necessário para cookies HttpOnly (Refresh Token) funcionarem
// Necessário para cookies HttpOnly (Refresh Token) funcionarem
2export const api = axios.create({
export const api = axios.create({
3  baseURL: process.env.NEXT_PUBLIC_API_URL,
  baseURL: process.env.NEXT_PUBLIC_API_URL,
4  withCredentials: true, // ← OBRIGATÓRIO para cookies cross-origin
  withCredentials: true, // ← OBRIGATÓRIO para cookies cross-origin
5});
});
6

7// Equivalent em fetch:
// Equivalent em fetch:
8// fetch(url, { credentials: 'include' })
// fetch(url, { credentials: 'include' })

CORS e CSRF: Relação e Diferenças

CORS e CSRF (Cross-Site Request Forgery) são conceitos relacionados mas distintos:

CORS previne que JavaScript em outro domínio leia a resposta de uma requisição à sua API. Mas não previne que um site malicioso submeta um formulário HTML para sua API — formulários não são afetados por CORS.
CSRF ataca via formulários ou tags de imagem que submetem requisições sem JavaScript. A proteção é o SameSite Cookie (SameSite=Strict ou Lax) ou um token CSRF no header.
SameSite=Strict impede que o cookie seja enviado em qualquer requisição cross-origin — incluindo formulários. É a defesa mais forte contra CSRF.

Configuração de cookies com SameSite

1// Refresh Token com proteção CSRF via SameSite
// Refresh Token com proteção CSRF via SameSite
2res.cookie('refresh_token', refreshToken, {
res.cookie('refresh_token', refreshToken, {
3  httpOnly: true,         // Não acessível via JavaScript (XSS)
  httpOnly: true,         // Não acessível via JavaScript (XSS)
4  secure: true,           // Apenas HTTPS
  secure: true,           // Apenas HTTPS
5  sameSite: 'strict',     // Não enviado em requisições cross-origin (CSRF)
  sameSite: 'strict',     // Não enviado em requisições cross-origin (CSRF)
6  maxAge: 30 * 24 * 60 * 60 * 1000,
  maxAge: 30 * 24 * 60 * 60 * 1000,
7  path: '/auth/refresh',  // Enviado apenas para esta rota
  path: '/auth/refresh',  // Enviado apenas para esta rota
8});
});
9

10// NOTA: sameSite: 'strict' + credentials: true no CORS funcionam juntos.
// NOTA: sameSite: 'strict' + credentials: true no CORS funcionam juntos.
11// O browser só envia o cookie quando a requisição vem do domínio autorizado.
// O browser só envia o cookie quando a requisição vem do domínio autorizado.

Testando CORS com Variáveis de Ambiente

.env.development

1# Desenvolvimento: permite localhost em múltiplas portas
# Desenvolvimento: permite localhost em múltiplas portas
2ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001

.env.production

1# Produção: apenas domínios reais
# Produção: apenas domínios reais
2ALLOWED_ORIGINS=https://app.suaempresa.com,https://painel.suaempresa.com
ALLOWED_ORIGINS=https://app.suaempresa.com,https://painel.suaempresa.com

Nunca use `origin: '' com credentials: true** — o navegador vai rejeitar com erro. E nunca use origin: '*'` em uma API que lida com dados sensíveis de usuários autenticados. Qualquer site da internet poderia fazer requisições em nome dos seus usuários.

Conclusão

CORS bem configurado protege seus usuários de ataques de cross-origin JavaScript enquanto permite que seus próprios frontends se comuniquem com a API. A configuração correta usa uma whitelist de origens carregada de variáveis de ambiente, credentials: true para cookies, maxAge para cachear preflights, e SameSite=Strict nos cookies para complementar a proteção contra CSRF.