Quando sua aplicação frontend chama uma API hospedada em uma origem diferente, os navegadores bloqueiam a requisição por padrão. O compartilhamento de recursos de origem cruzada (CORS) permite controlar quais origens, métodos e cabeçalhos são permitidos nessas requisições de origem cruzada.
Os gateways cloud do Microservices Engine (MSE) oferecem suporte a políticas de CORS no nível da rota. Associe uma política de CORS a uma rota para definir quais requisições de origem cruzada o seu backend aceitará.
Como o CORS funciona
Uma requisição de origem cruzada ocorre quando uma página web solicita um recurso de um domínio, subdomínio, porta ou protocolo diferente. Por exemplo, uma página em https://app.example.com chamando https://api.example.com é uma requisição de origem cruzada.
Quando um navegador envia uma requisição de origem cruzada, ele inclui um cabeçalho Origin que identifica o domínio solicitante. O gateway verifica esse cabeçalho em relação à sua política de CORS e responde com os cabeçalhos Access-Control-* apropriados usando TLS.
Para requisições simples (GET ou POST básicos com cabeçalhos padrão), o navegador envia a requisição diretamente e verifica os cabeçalhos CORS na resposta. Requisições não simples — como as que usam PUT ou DELETE, ou as que incluem cabeçalhos personalizados — acionam primeiro uma requisição OPTIONS de preflight. O navegador só envia a requisição real após o preflight confirmar que a origem, o método e os cabeçalhos são permitidos.
Origem permitida (a requisição é bem-sucedida):
GET /api/items HTTP/1.1
Host: api.example.com
Origin: https://app.example.com
HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://app.example.comOrigem não reconhecida (o navegador bloqueia a resposta):
GET /api/items HTTP/1.1
Host: api.example.com
Origin: https://unknown-site.com
HTTP/1.1 200 OK
# No Access-Control-Allow-Origin header -- browser blocks this responsePré-requisitos
Antes de começar, verifique se você tem:
Um gateway cloud do MSE com pelo menos uma rota configurada
O service de backend real vinculado à rota (as políticas de CORS não têm efeito em service mock)
Configure uma política de CORS
Acesse o MSE console. Na barra de navegação superior, selecione uma região.
No painel de navegação à esquerda, escolha Cloud-native Gateway > Gateways. Na página Gateways, clique em nome do gateway.
No painel de navegação à esquerda, clique em Routes e, em seguida, clique na aba Routes.
Encontre a rota que deseja configurar e clique em Policies na coluna Actions.
Na aba Policies, clique em CORS.
Agora configure os seguintes parâmetros e clique em Save.
|
Parâmetro |
Mapeia para o cabeçalho HTTP |
Descrição |
|
Allowed Origins |
|
Origens com permissão para acessar seu backend por meio de um navegador. Para permitir todas as origens, insira |
|
Allowed Methods |
|
Métodos HTTP permitidos em requisições CORS. Valores válidos: GET, POST, PUT, DELETE, HEAD, OPTIONS e PATCH. |
|
Allowed Request Headers |
|
Cabeçalhos de requisição permitidos além dos cabeçalhos integrados do navegador. Para permitir todos os cabeçalhos, insira |
|
Allowed Response Headers |
|
Cabeçalhos de resposta que navegadores e JavaScript podem acessar. Para expor todos os cabeçalhos, insira |
|
Allow to Carry Credentials |
|
Para credenciais, defina se deve incluir credenciais (cookies, cabeçalhos de autorização ou certificados de cliente TLS) em requisições CORS. Consulte a seção Origem curinga com credenciais em Problemas comuns para uma restrição importante. |
|
Precheck Expiration Time |
|
Duração máxima (em segundos) que o navegador armazena em cache as respostas OPTIONS de preflight. Um período de cache maior reduz o número de requisições de preflight. |
|
Enable |
N/A |
Para controlar o CORS, ative ou desative a política de CORS. Quando ativada, as requisições de origem cruzada são avaliadas em relação a esta política. Quando desativada, todas as requisições de origem cruzada para esta rota são rejeitadas. |
Se você usar um plugin de autenticação global, como JWT ou OAuth2, junto com uma política de CORS, as requisições do navegador podem retornar erros de CORS mesmo que as requisições de clientes de API como o Postman sejam bem-sucedidas.
Causa: Os navegadores enviam automaticamente uma requisição OPTIONS de preflight antes da requisição real de origem cruzada. A requisição de preflight não carrega um cabeçalho Authorization, por isso é interceptada pelo plugin de autenticação e retorna um erro 403, o que causa a falha no handshake do CORS.
Agora verifique a política de CORS
Depois que você salve a política, envie uma requisição OPTIONS de preflight para o endpoint da sua rota e verifique os cabeçalhos CORS na resposta.
curl -I \
-H "Origin: http://example.com" \
-H "Host: www.test.com" \
-X OPTIONS \
http://<gateway-ip>/demo/item/listSubstitua <gateway-ip> pelo endereço IP do seu gateway cloud.
Uma resposta bem-sucedida inclui cabeçalhos CORS que correspondem à configuração da sua política:
HTTP/1.1 200 OK
access-control-allow-origin: http://example.com
access-control-allow-credentials: true
access-control-expose-headers: *
server: istio-envoySe o cabeçalho access-control-allow-origin estiver ausente ou não corresponder ao valor Origin na sua requisição, revise a configuração de Allowed Origins.
Problemas comuns
Origem curinga com credenciais
Não defina Allowed Origins como * e ative Allow to Carry Credentials ao mesmo tempo. A especificação CORS proíbe o uso de uma origem curinga com credenciais. Os navegadores rejeitam respostas que incluem tanto Access-Control-Allow-Origin: * quanto Access-Control-Allow-Credentials: true.
Para permitir credenciais de várias origens, liste cada origem individualmente em vez de usar um curinga.
A política de CORS não tem efeito
A política de CORS não tem efeito em service mock. Certifique-se de que um service de backend real esteja vinculado à rota.
Se a política ainda não tiver efeito após vincular um service de backend, verifique o seguinte:
A opção Enable está ativada para a política de CORS.
A origem na requisição corresponde a uma das entradas em Allowed Origins.
O método HTTP corresponde a uma das entradas em Allowed Methods.
A requisição de preflight falha
Se o navegador enviar uma requisição OPTIONS de preflight e receber um erro, verifique o seguinte:
A lista Allowed Methods inclui OPTIONS.
A lista Allowed Request Headers inclui todos os cabeçalhos personalizados que o cliente envia.
Como determinar se um problema de CORS é causado pelo gateway do MSE ou pelo service de backend?
Execute as seguintes etapas:
-
No painel Network do navegador, verifique os cabeçalhos de resposta da requisição OPTIONS de preflight.
Se a resposta incluir cabeçalhos CORS como
Access-Control-Allow-Origine o tempo de resposta for muito curto (geralmente alguns milissegundos), o gateway do MSE lidou com o CORS corretamente.Se a resposta não incluir cabeçalhos CORS e o status for 200 ou 403, o gateway pode não estar correspondendo à rota, ou a requisição está sendo encaminhada para o backend sem o processamento de CORS.
-
Desative temporariamente a configuração de CORS no service de backend e dependa exclusivamente do gateway do MSE para o tratamento de CORS.
Se os erros de CORS pararem, o gateway do MSE está configurado corretamente e o problema é causado por um conflito com a configuração de CORS do backend.
Se os erros de CORS persistirem, verifique as regras de correspondência de rota do MSE, incluindo a correspondência de nome de domínio e caminho.
Ativar o Force HTTPS causa problemas de CORS?
Não. O Force HTTPS apenas redireciona requisições HTTP para HTTPS e não afeta o processamento de CORS. Ativar o Force HTTPS não causa erros de CORS.
Se você encontrar erros de CORS e as requisições não estiverem chegando ao gateway, isso geralmente é uma restrição no nível do navegador. Solucione o problema a partir do lado do frontend.
Se a política não for necessária, exclua a configuração.