Explicador de Cabeçalho CORS

O Explicador de Cabeçalho CORS fornece uma referência interativa e validador de configuração para cabeçalhos Cross-Origin Resource Sharing, ajudando você a compreender, debugar e corrigir erros CORS sem ciclos de deployment de tentativa-e-erro. Digite sua origem de requisição, método e cabeçalhos customizados ao lado dos cabeçalhos de resposta CORS do servidor, e veja instantaneamente se o navegador permitiria ou bloquearia a requisição -- com uma explicação clara do por quê.

Compreendendo CORS

Se você já viu a mensagem "Access to XMLHttpRequest has been blocked by CORS policy" em seu console de navegador, você encontrou um dos mecanismos de segurança mais comuns e mais confusos da web. CORS significa Cross-Origin Resource Sharing, e existe para proteger usuários de websites maliciosos que tentam fazer requisições a outros sites em nome do usuário. Sem CORS, qualquer página web que você visita poderia silenciosamente enviar requisições para a API do seu banco usando sua sessão logada -- CORS previne isso requerendo que o servidor do banco explicitamente opte em receber requisições de outras origens.

Uma origem é definida pela combinação de scheme, host e porta: https://app.example.com e https://api.example.com são diferentes origens mesmo que compartilhem o mesmo domínio raiz. Quando seu JavaScript frontend em https://app.example.com faz uma requisição fetch para https://api.example.com/data, o navegador verifica se o servidor de API enviou os cabeçalhos CORS certos dizendo que permite requisições de https://app.example.com. Se os cabeçalhos estão faltando ou incorretos, o navegador bloqueia a resposta de atingir seu JavaScript, mesmo que o servidor realmente tenha processado a requisição e enviado dados de volta.

A confusão em torno de CORS vem de seu design em camadas. Requisições simples -- GET ou POST básico com cabeçalhos padrão -- vão diretamente, e o navegador verifica os cabeçalhos CORS na resposta. Mas qualquer requisição que use cabeçalhos customizados, tipos de conteúdo não-padrão ou métodos como PUT ou DELETE dispara uma verificação de preflight: o navegador envia uma requisição OPTIONS primeiro para perguntar ao servidor se aceitará a requisição real. O servidor deve responder esse preflight com os cabeçalhos Access-Control-Allow-* corretos antes do navegador enviar a requisição actual. Essa ferramenta simula ambos os cenários para que você possa validar sua configuração antes de fazer deploy.

Como Verificar uma Configuração CORS

1. Digite a origem de requisição (ex: https://app.example.com), método HTTP e quaisquer cabeçalhos customizados que seu frontend envia.
2. Digite os cabeçalhos de resposta CORS do servidor (Access-Control-Allow-Origin, Access-Control-Allow-Methods, etc).
3. Clique em Verificar para simular validação CORS do navegador.
4. Revise o resultado: a ferramenta explica se a requisição seria permitida ou bloqueada e identifica a razão exacta para qualquer falha.

Exemplos de Cabeçalho CORS

Requisição Simples (Permitida)

Resultado: Permitida. A origem combina exatamente.

Requisição de Preflight com Cabeçalhos Customizados (Permitida)

Resultado: Permitida. A origem, método e cabeçalhos todos combinam. Preflight está cacheado por 24 horas.

Requisição de Credenciais (Bloqueada)

Resultado: Bloqueada. Quando Access-Control-Allow-Credentials é true, o cabeçalho Access-Control-Allow-Origin não pode ser o wildcard * -- deve especificar a exacta origem.

Quando Usar o Explicador de Cabeçalho CORS

• Depurando "CORS error" em consoles de navegador -- Cole seus detalhes de requisição e cabeçalhos de servidor para descobrir exatamente por que o navegador está bloqueando a requisição.
• Configurando API CORS -- Valide seus cabeçalhos Access-Control-* antes de fazer deploy em produção.
• Configurando cabeçalhos de proxy reverse ou CDN -- Teste passthrough de cabeçalho CORS quando usando CloudFront, Cloudflare ou nginx como proxy.
• Compreendendo requisições preflight vs. simples -- Saiba quais características de requisição disparam uma requisição OPTIONS preflight.
• Corrigindo problemas de credenciais e cookie -- Diagnostique por que cookies ou cabeçalhos Authorization não estão sendo enviados em requisições entre origens.
• Treinamento e documentação -- Use o verificador interativo como uma ferramenta de ensino para desenvolvedores aprendendo CORS pela primeira vez.

Como CORS Funciona

Requisições Simples vs. Requisições de Preflight

Navegadores classificam requisições entre origens em duas categorias:

Requisições simples são enviadas diretamente sem uma verificação de preflight. Uma requisição é "simples" quando usa GET, HEAD ou POST com apenas cabeçalhos padrão (Accept, Accept-Language, Content-Language, Content-Type limitado a application/x-www-form-urlencoded, multipart/form-data ou text/plain).

Requisições de preflight são disparadas para qualquer coisa fora dos critérios de requisição simples. O navegador envia uma requisição OPTIONS primeiro, e o servidor deve responder com cabeçalhos Access-Control-Allow-* apropriados antes da requisição actual ser enviada.

Referência de Cabeçalho CORS

Erros Comuns de CORS

• Definindo Access-Control-Allow-Origin: * com Access-Control-Allow-Credentials: true -- essa combinação é explicitamente proibida pela spec.
• Esquecendo de incluir Content-Type em Access-Control-Allow-Headers quando enviando JSON -- application/json não é um tipo de conteúdo "simples".
• Não manipulando o método OPTIONS de preflight no servidor, resultando em uma resposta 405 Method Not Allowed.
• Omitindo Access-Control-Expose-Headers e se perguntando por que JavaScript não pode ler cabeçalhos de resposta customizados.

Fluxo de Validação CORS

Navegador                                    Servidor
  |                                          |
  |-- É uma requisição simples? ----------->|
  |   (GET/HEAD/POST, cabeçalhos padrão)    |
  |                                          |
  |   SIM: Envie requisição diretamente      |
  |   NÃO: Envie preflight OPTIONS primeiro |
  |                                          |
  |<--- Resposta de preflight ------------------|
  |   Access-Control-Allow-Origin: ...       |
  |   Access-Control-Allow-Methods: ...      |
  |   Access-Control-Allow-Headers: ...      |
  |                                          |
  |-- Verificar: Origem combina? ----------->|
  |-- Verificar: Método permitido? -------->|
  |-- Verificar: Cabeçalhos permitidos? ---->|
  |                                          |
  |   TUDO PASSA: Envie requisição actual    |
  |   QUALQUER FALHA: Bloqueie e registre erro CORS|

Dicas Práticas para Configuração CORS

A abordagem mais segura para configuração CORS é começar com as configurações mais restritivas e abrir apenas o que sua aplicação precisa. Comece especificando as exactas origens que devem ter acesso em vez de usar *. Se seu frontend está em https://app.example.com, defina Access-Control-Allow-Origin: https://app.example.com explicitamente. Isso previne qualquer outro site de fazer requisições entre origens para sua API. Se você precisa suportar múltiplas origens, implemente verificação dinâmica de origem no servidor -- leia o cabeçalho de requisição Origin, verifique-o contra sua lista de permissão e ecoize-o de volta na resposta.

Caching de preflight é uma otimização frequentemente negligenciada. Sem Access-Control-Max-Age, o navegador envia uma requisição OPTIONS preflight antes de toda requisição entre origens. Em uma aplicação que faz chamadas de API frequentes, isso dobra o número de requisições. Definindo Access-Control-Max-Age: 3600 (1 hora) diz ao navegador para cachear o resultado de preflight, eliminando requisições OPTIONS redundantes. Note que a maioria dos navegadores capeiam isso em torno de 7.200 segundos (2 horas), e Chrome o capeiam em 2 horas mesmo se você definir um valor mais alto.

Quando sua API precisa retornar cabeçalhos de resposta customizados que JavaScript deveria ler (como info de paginação em X-Total-Count ou IDs de requisição em X-Request-ID), você deve listá-los em Access-Control-Expose-Headers. Por padrão, JavaScript pode apenas ler um pequeno conjunto de cabeçalhos de resposta "CORS-safelisted": Cache-Control, Content-Language, Content-Type, Expires, Last-Modified e Pragma. Qualquer cabeçalho customizado é invisível para seu código frontend a menos que você o exponha explicitamente. Essa é uma fonte comum de confusão ao debugar problemas de paginação ou display de limite de taxa.

Perguntas Frequentes

Por que minha requisição funciona em Postman mas falha no navegador?

Postman e outros clientes de API não executam CORS porque CORS é um mecanismo de segurança apenas do navegador. A política de mesma origem é executada pelo navegador para proteger usuários de scripts maliciosos. Requisições servidor-para-servidor não são afetadas por CORS.

Posso usar Access-Control-Allow-Origin: * com cookies?

Não. Quando a requisição inclui credenciais (cookies, autenticação HTTP), o servidor deve responder com a exacta origem solicitante, não *. Defina Access-Control-Allow-Origin: https://app.example.com e Access-Control-Allow-Credentials: true juntos.

O que é Access-Control-Max-Age e devo defini-lo?

Diz ao navegador quanto tempo cachear a resposta de preflight. Sem ele, o navegador envia uma requisição OPTIONS antes de toda requisição entre origens. Defini-lo para 86400 (24 horas) reduz overhead de preflight significativamente. A maioria dos navegadores o capeiam em 7200 segundos (2 horas) independente do valor que você definir.

Por que recebo erro CORS mesmo que o servidor retorne 200?

CORS é executado pelo navegador, não pelo servidor. O servidor processa a requisição e envia resposta 200, mas se a resposta carece do cabeçalho Access-Control-Allow-Origin correto, o navegador bloqueia JavaScript de acessar dados da resposta. A requisição é bem-sucedida no lado do servidor -- você apenas não pode ler o resultado do seu frontend.

Como manipulo CORS para conexões WebSocket?

Conexões WebSocket não usem CORS. O handshake HTTP inicial que faz upgrade para WebSocket não está sujeito a CORS preflight. No entanto, você ainda deveria validar o cabeçalho Origin no lado do servidor durante o handshake WebSocket para prevenir WebSocket hijacking entre origens.

Posso usar CORS para restringir quais servidores podem chamar minha API?

Não. CORS apenas restringe requisições baseadas em navegador. Qualquer servidor, script ou ferramenta de linha de comando pode chamar sua API diretamente sem restrições CORS. Para autenticação servidor-para-servidor, use chaves de API, tokens OAuth ou TLS mútuo. CORS é especificamente uma feature de segurança de navegador, não um mecanismo de controle de acesso geral.

Ferramentas Relacionadas

• Formatador de Cabeçalho HTTP - Analise e formate cabeçalhos HTTP incluindo cabeçalhos CORS
• Lookup de Código de Status HTTP - Procure códigos de status retornados durante falhas de preflight
• Analisador de Cabeçalho de Cookie - Analise cookies que interagem com configurações de credencial CORS
• Construtor de Comando curl - Construa comandos curl para testar endpoints habilitados com CORS
• Lookup de Tipo MIME - Procure valores Content-Type que afetam decisões CORS simples vs. preflight