Testador CORS Online: Diagnostique Problemas de Compartilhamento de Recursos entre Origens
· 12 min de leitura
Índice
- Entendendo CORS e Sua Importância
- Como CORS Funciona: O Mergulho Técnico Profundo
- Problemas Comuns de CORS e Mensagens de Erro
- Usando um Testador CORS Efetivamente
- Exemplos Práticos de Diagnóstico de Problemas CORS
- Implementando CORS no Lado do Servidor
- Cabeçalhos CORS Explicados em Detalhe
- Considerações de Segurança e Melhores Práticas
- Guia Avançado de Solução de Problemas
- Estratégias de Teste para Configuração CORS
- Perguntas Frequentes
- Artigos Relacionados
Entendendo CORS e Sua Importância
Compartilhamento de Recursos entre Origens (CORS) é um mecanismo de segurança implementado em navegadores web que controla como aplicações web podem solicitar recursos de diferentes origens. Pense nisso como um segurança de uma boate—ele decide quem entra e quem não entra com base em um conjunto específico de regras.
Por padrão, navegadores aplicam a Política de Mesma Origem (SOP), que impede JavaScript executando em um domínio de acessar recursos em outro domínio. Este é um recurso de segurança fundamental que protege usuários de scripts maliciosos. No entanto, aplicações web modernas frequentemente precisam se comunicar com APIs e serviços hospedados em diferentes domínios, e é aí que CORS entra.
CORS fornece uma maneira padronizada para servidores dizerem aos navegadores: "Sim, está tudo bem para este site específico acessar meus recursos." Sem a configuração adequada de CORS, solicitações legítimas entre origens serão bloqueadas, quebrando funcionalidades em suas aplicações web.
Dica profissional: CORS é um recurso de segurança aplicado pelo navegador. Ferramentas como cURL ou Postman não encontrarão problemas de CORS porque não são navegadores. Sempre teste configurações CORS em um ambiente de navegador real.
Considere um cenário do mundo real: Você está construindo uma plataforma de e-commerce onde o frontend está hospedado em https://minhaloja.com, mas sua API de inventário de produtos está em https://api.servico-inventario.com. Sem cabeçalhos CORS, seu JavaScript frontend não conseguirá buscar dados de produtos, deixando seus clientes olhando para prateleiras vazias.
CORS se torna ainda mais crítico quando você está trabalhando com:
- APIs de terceiros que seu frontend precisa acessar diretamente
- Arquiteturas de microsserviços onde diferentes serviços rodam em diferentes domínios
- Redes de Distribuição de Conteúdo (CDNs) servindo recursos de diferentes origens
- Aplicações de Página Única (SPAs) que se comunicam com APIs backend
- Fontes web, imagens ou outros recursos carregados de domínios externos
Como CORS Funciona: O Mergulho Técnico Profundo
Entender como CORS funciona por baixo dos panos ajuda você a diagnosticar problemas mais efetivamente. O mecanismo CORS envolve dois tipos de solicitações: solicitações simples e solicitações preflight.
Solicitações Simples
Uma solicitação simples é aquela que atende todas estas condições:
- Usa um destes métodos HTTP: GET, HEAD ou POST
- Inclui apenas cabeçalhos seguros para CORS como Accept, Accept-Language, Content-Language ou Content-Type
- Se Content-Type for usado, deve ser application/x-www-form-urlencoded, multipart/form-data ou text/plain
Para solicitações simples, o navegador envia a solicitação diretamente com um cabeçalho Origin. O servidor responde com um cabeçalho Access-Control-Allow-Origin indicando se a origem é permitida. Se o cabeçalho corresponder à origem solicitante (ou estiver definido como *), o navegador permite que a resposta seja lida pelo código JavaScript.
Solicitações Preflight
Qualquer solicitação que não atenda aos critérios de solicitação simples aciona uma solicitação preflight. Esta é uma solicitação OPTIONS enviada pelo navegador antes da solicitação real para verificar se o protocolo CORS é compreendido e se a solicitação real é segura para enviar.
A solicitação preflight inclui cabeçalhos como:
Access-Control-Request-Method: O método HTTP da solicitação realAccess-Control-Request-Headers: Cabeçalhos personalizados que serão enviados com a solicitação realOrigin: A origem fazendo a solicitação
O servidor deve responder ao preflight com cabeçalhos CORS apropriados indicando o que é permitido. Somente se o preflight for bem-sucedido o navegador envia a solicitação real.
Dica rápida: Solicitações preflight podem impactar o desempenho. Use o cabeçalho Access-Control-Max-Age para armazenar em cache respostas preflight e reduzir o número de solicitações OPTIONS que seu servidor precisa lidar.
Problemas Comuns de CORS e Mensagens de Erro
Erros CORS estão entre os problemas mais frustrantes que desenvolvedores encontram. Vamos detalhar os problemas mais comuns e o que eles realmente significam.
Cabeçalho Access-Control-Allow-Origin Ausente
Este é o erro CORS mais comum que você verá. O console do navegador mostrará algo como:
Acesso ao fetch em 'https://api.exemplo.com/data' da origem 'https://meuapp.com' foi bloqueado pela política CORS: Nenhum cabeçalho 'Access-Control-Allow-Origin' está presente no recurso solicitado.
Isso significa que o servidor não incluiu o cabeçalho CORS necessário em sua resposta. A correção é direta: configure seu servidor para enviar o cabeçalho Access-Control-Allow-Origin com a origem específica ou * para APIs públicas.
Método HTTP Incorreto
Quando você tenta usar um método HTTP que o servidor não permitiu explicitamente, você verá um erro como:
Acesso ao fetch em 'https://api.exemplo.com/data' da origem 'https://meuapp.com' foi bloqueado pela política CORS: Método PUT não é permitido por Access-Control-Allow-Methods na resposta preflight.
Isso acontece durante a fase preflight. Seu servidor precisa incluir o método HTTP no cabeçalho Access-Control-Allow-Methods.
Credenciais Não Suportadas
Se você está tentando enviar cookies ou cabeçalhos de autenticação mas o servidor não está configurado para isso, você encontrará:
Acesso ao fetch em 'https://api.exemplo.com/data' da origem 'https://meuapp.com' foi bloqueado pela política CORS: O valor do cabeçalho 'Access-Control-Allow-Credentials' na resposta é '' que deve ser 'true' quando o modo de credenciais da solicitação é 'include'.
Para corrigir isso, o servidor deve enviar Access-Control-Allow-Credentials: true, e importante, não pode usar Access-Control-Allow-Origin: * quando credenciais estão envolvidas—deve especificar a origem exata.
Cabeçalhos Personalizados Não Permitidos
Aplicações modernas frequentemente usam cabeçalhos personalizados para chaves de API, tokens de autenticação ou outros metadados. Se estes não forem explicitamente permitidos, você verá:
Campo de cabeçalho de solicitação x-api-key não é permitido por Access-Control-Allow-Headers na resposta preflight.
A solução é incluir seus cabeçalhos personalizados no cabeçalho de resposta Access-Control-Allow-Headers.
| Tipo de Erro | Causa Comum | Correção Rápida |
|---|---|---|
| Sem Access-Control-Allow-Origin | Servidor não configurado para CORS | Adicionar o cabeçalho às respostas do servidor |
| Método não permitido | Método HTTP não está na lista permitida | Atualizar Access-Control-Allow-Methods |
| Credenciais não suportadas | Cabeçalho de credenciais ausente | Definir Access-Control-Allow-Credentials: true |
| Cabeçalho não permitido | Cabeçalho personalizado não está na lista branca | Adicionar a Access-Control-Allow-Headers |
| Curinga com credenciais | Usando * com modo de credenciais | Especificar origem exata em vez de * |
Usando um Testador CORS Efetivamente
Um testador CORS é uma ferramenta inestimável para diagnosticar problemas entre origens sem escrever código. Ele simula solicitações do navegador e mostra exatamente quais cabeçalhos CORS estão sendo enviados e recebidos. Você pode usar nosso Testador CORS para diagnosticar problemas rapidamente.
O Que um Bom Testador CORS Deve Fazer
Uma ferramenta eficaz de teste CORS deve fornecer:
- A capacidade de especificar a URL de destino e origem
- Opções para selecionar diferentes métodos HTTP (GET, POST, PUT, DELETE, etc.)
- Configuração de cabeçalho personalizado para testar cenários específicos
- Exibição clara de cabeçalhos de solicitação e resposta
- Indicação se a verificação CORS passou ou falhou
- Mensagens de erro detalhadas explicando o que deu errado
Processo de Teste Passo a Passo
Aqui está como usar um testador CORS efetivamente:
- Insira a URL do endpoint da API que você quer testar
- Especifique a origem que fará a solicitação (seu domínio frontend)
- Selecione o método HTTP que sua aplicação usará
- Adicione quaisquer cabeçalhos personalizados que sua aplicação envia (como Authorization ou X-API-Key)
- Execute o teste e examine os resultados
- Revise os cabeçalhos de resposta para ver quais políticas CORS estão em vigor
- Identifique cabeçalhos ausentes ou incorretos que precisam ser configurados no servidor
Dica profissional: Sempre teste com a origem exata que sua aplicação de produção usará. Alguns servidores têm configurações CORS específicas de origem que podem funcionar para localhost mas falhar para seu domínio de produção.
Interpretando Resultados de Teste
Quando você executa um teste CORS, preste atenção a estes indicadores chave:
- Status do preflight: A solicitação OPTIONS foi bem-sucedida? Se não, seu servidor pode não estar lidando com solicitações preflight corretamente.
- Valor de Access-Control-Allow-Origin: Ele corresponde à sua origem ou está definido como *? Se não corresponder, a solicitação falhará.
- Métodos permitidos: Seu método HTTP pretendido está listado em Access-Control-Allow-Methods?
- Cabeçalhos permitidos: Todos os seus cabeçalhos personalizados estão incluídos em Access-Control-Allow-Headers?
- Suporte a credenciais: Se você precisa enviar cookies, Access-Control-Allow-Credentials está definido como true?
Você também pode usar nosso Analisador de Cabeçalhos HTTP para obter um detalhamento detalhado de todos os cabeçalhos sendo enviados e recebidos, o que complementa perfeitamente o teste CORS.
Exemplos Práticos de Diagnóstico de Problemas CORS
Exemplo 1: Integração de Mídia Social
Digamos que você está construindo um painel de mídia social que agrega postagens de múltiplas plataformas. Seu frontend em https://painel.exemplo.com precisa buscar dados de https://api.midiasocial.com.
Você está fazendo uma solicitação POST para criar uma nova postagem, mas continua recebendo erros CORS. Aqui está como diagnosticar:
- Abra seu testador CORS e insira
https://api.midiasocial.com/posts - Defina a origem como
https://painel.exemplo.com - Selecione POST como o método
- Adicione o cabeçalho Content-Type:
application/json - Adicione seu cabeçalho Authorization:
Bearer seu-token-aqui - Execute o teste
O teste revela que o servidor permite apenas solicitações GET. O cabeçalho Access-Control-Allow-Methods mostra: GET, HEAD, OPTIONS. Você precisa contatar o provedor da API para habilitar solicitações POST, ou verificar se há um endpoint diferente para criar postagens.
Exemplo 2: Sistema de Inventário de E-commerce
Seu site de e-commerce em https://loja.exemplo.com puxa dados de inventário de https://inventario.exemplo.com. A API requer um cabeçalho personalizado X-Shop-ID para identificar qual loja está fazendo a solicitação.
O teste revela o erro: "Campo de cabeçalho de solicitação x-shop-id não é permitido p