CORS

  • Artigo

APLICA-SE A: Todas as camadas de gerenciamento de API

A cors política adiciona suporte a compartilhamento de recursos entre origens (CORS) a uma operação ou a uma API para permitir chamadas entre domínios de clientes baseados em navegador.

Nota

Defina os elementos da política e os elementos filho na ordem fornecida na declaração de política. Para ajudá-lo a configurar essa política, o portal fornece um editor guiado baseado em formulários. Saiba mais sobre como definir ou editar políticas de Gerenciamento de API.

Declaração de política

<cors allow-credentials="false | true" terminate-unmatched-request="true | false">
    <allowed-origins>
        <origin>origin uri</origin>
    </allowed-origins>
    <allowed-methods preflight-result-max-age="number of seconds">
        <method>HTTP verb</method>
    </allowed-methods>
    <allowed-headers>
        <header>header name</header>
    </allowed-headers>
    <expose-headers>
        <header>header name</header>
    </expose-headers>
</cors>

Atributos

Nome Descrição Necessário Predefinição
permitir-credenciais O Access-Control-Allow-Credentials cabeçalho na resposta de comprovação será definido com o valor desse atributo e afetará a capacidade do cliente de enviar credenciais em solicitações entre domínios. São permitidas expressões de política. Não false
terminate-unmatched-request Controla o processamento de solicitações de origem cruzada que não correspondem às configurações de política. São permitidas expressões de política.

Quando OPTIONS a solicitação é processada como uma solicitação de comprovação e Origin o cabeçalho não corresponde às configurações de política:
- Se o atributo estiver definido como true, encerre imediatamente a solicitação com uma resposta vazia 200 OK
- Se o atributo estiver definido como false, verifique se há outras políticas no escopo cors que são filhos diretos do elemento de entrada e aplique-as. Se nenhuma cors política for encontrada, encerre a solicitação com uma resposta vazia 200 OK .

Quando GET a solicitação inclui HEAD o cabeçalho (e, portanto, é processada Origin como uma simples solicitação de origem cruzada) e não corresponde às configurações de política:
- Se o atributo estiver definido como true, encerre imediatamente a solicitação com uma resposta vazia 200 OK .
- Se o atributo estiver definido como false, permita que a solicitação prossiga normalmente e não adicione cabeçalhos CORS à resposta.		 Não true

Elementos

Nome Descrição Necessário Predefinição
origens permitidas Contém origin elementos que descrevem as origens permitidas para solicitações entre domínios. allowed-origins pode conter um único origin elemento que especifica * para permitir qualquer origem ou um ou mais origin elementos que contêm um URI. Sim N/A
métodos permitidos Este elemento é necessário se métodos diferentes ou GET POST permitidos. Contém method elementos que especificam os verbos HTTP suportados. O valor * indica todos os métodos. Não Se esta seção não estiver presente GET e POST for suportada.
cabeçalhos permitidos Este elemento contém header elementos que especificam nomes dos cabeçalhos que podem ser incluídos na solicitação. Sim N/A
expor-cabeçalhos Este elemento contém header elementos que especificam nomes dos cabeçalhos que serão acessíveis pelo cliente. No N/A

Atenção

Use o curinga * com cuidado nas configurações de política. Essa configuração pode ser excessivamente permissiva e pode tornar uma API mais vulnerável a determinadas ameaças à segurança da API.

elementos de origem permitida

Nome Descrição Necessário Predefinição
origem O valor pode ser * para permitir todas as origens ou um URI que especifica uma única origem. O URI deve incluir um esquema, host e porta. Não inclua as aspas. Sim Se a porta for omitida em um URI, a porta 80 será usada para HTTP e a porta 443 será usada para HTTPS.

atributos allowed-methods

Nome Descrição Necessário Predefinição
pré-voo-resultado-max-idade O Access-Control-Max-Age cabeçalho na resposta de comprovação será definido com o valor desse atributo e afetará a capacidade do agente do usuário de armazenar em cache a resposta de comprovação. São permitidas expressões de política. Não 0

elementos de métodos permitidos

Nome Descrição Necessário Predefinição
método Especifica um verbo HTTP. São permitidas expressões de política. Pelo menos um method elemento é necessário se a allowed-methods seção estiver presente. N/A

elementos de cabeçalhos permitidos

Nome Descrição Necessário Predefinição
cabeçalho Especifica um nome de cabeçalho. Pelo menos um header elemento é necessário se allowed-headers essa secção estiver presente. N/A

elementos expose-headers

Nome Descrição Necessário Predefinição
cabeçalho Especifica um nome de cabeçalho. Pelo menos um header elemento é necessário se expose-headers essa secção estiver presente. N/A

Utilização

Notas de utilização

  • Você pode configurar a cors política em mais de um escopo (por exemplo, no escopo do produto e no escopo global). Certifique-se de que o base elemento esteja configurado nos escopos de operação, API e produto para herdar as políticas necessárias nos escopos pai.
  • Apenas a apólice cors é avaliada no pedido durante o OPTIONS pré-voo. As restantes políticas configuradas são avaliadas no pedido aprovado.
  • Esta política só pode ser utilizada uma vez numa secção de política.

Sobre o CORS

CORS é um padrão baseado em cabeçalho HTTP que permite que um navegador e um servidor interajam e determinem se devem ou não permitir solicitações de origem cruzada específicas (XMLHttpRequest chamadas feitas de JavaScript em uma página da Web para outros domínios). Isso permite mais flexibilidade do que permitir apenas solicitações de mesma origem, mas é mais seguro do que permitir todas as solicitações de origem cruzada.

O CORS especifica dois tipos de solicitações de origem cruzada:

  • Solicitações de comprovação (ou "comprovação") - O navegador primeiro envia uma solicitação HTTP usando o OPTIONS método para o servidor, para determinar se a solicitação real tem permissão para enviar. Se a resposta do servidor incluir o cabeçalho que permite o Access-Control-Allow-Origin acesso, o navegador segue com a solicitação real.

  • Solicitações simples - Essas solicitações incluem um ou mais cabeçalhos extras Origin , mas não acionam uma comprovação do CORS. Somente solicitações usando os GET métodos e HEAD e um conjunto limitado de cabeçalhos de solicitação são permitidas.

cors Cenários políticos

Configure a cors política no Gerenciamento de API para os seguintes cenários:

  • Ative a consola de teste interativa no portal do programador. Veja a documentação do portal do programador para obter detalhes.

    Nota

    Quando você habilita o CORS para o console interativo, por padrão, o Gerenciamento de API configura a cors política no escopo global.

  • Ative a Gestão de API para responder aos pedidos de verificação prévia ou passar por pedidos CORS simples quando os back-ends não fornecem o seu próprio suporte CORS.

    Nota

    Se uma solicitação corresponder a uma operação com um OPTIONS método definido na API, a lógica de processamento da solicitação de comprovação associada à cors política não será executada. Portanto, tais operações podem ser usadas para implementar lógica de processamento de comprovação personalizada - por exemplo, para aplicar a cors política apenas sob certas condições.

Problemas comuns de configuração

  • Chave de assinatura no cabeçalho - Se você configurar a cors política no escopo do produto e sua API usar autenticação de chave de assinatura, a política não funcionará quando a chave de assinatura for passada em um cabeçalho. Como solução, modifique os pedidos para incluírem uma chave de subscrição como parâmetro de consulta.
  • API com controle de versão de cabeçalho - Se você configurar a cors política no escopo da API e sua API usar um esquema de controle de versão de cabeçalho, a política não funcionará porque a versão é passada em um cabeçalho. Poderá ter de configurar um método de controlo de versões alternativo, como um caminho ou parâmetro de consulta.
  • Ordem da política - Você pode enfrentar um comportamento inesperado se a cors política não for a primeira política na seção de entrada. Selecione Calcular política efetiva no editor de políticas para verificar a ordem de avaliação da política em cada escopo. Geralmente, apenas a primeira cors política é aplicada.
  • Resposta vazia 200 OK - Em algumas configurações de política, certas solicitações de origem cruzada são concluídas com uma resposta vazia 200 OK . Essa resposta é esperada quando terminate-unmatched-request é definida como seu valor padrão de e uma solicitação de entrada tem um Origin cabeçalho que não corresponde a cors uma origem permitida configurada true na política.

Exemplo

Este exemplo demonstra como dar suporte a solicitações de comprovação, como aquelas com cabeçalhos personalizados ou métodos diferentes de GET e POST. Para oferecer suporte a cabeçalhos personalizados e outros verbos HTTP, use as allowed-methods seções e allowed-headers conforme mostrado no exemplo a seguir.

<cors allow-credentials="true">
    <allowed-origins>
        <!-- Localhost useful for development -->
        <origin>http://localhost:8080/</origin>
        <origin>http://example.com/</origin>
    </allowed-origins>
    <allowed-methods preflight-result-max-age="300">
        <method>GET</method>
        <method>POST</method>
        <method>PATCH</method>
        <method>DELETE</method>
    </allowed-methods>
    <allowed-headers>
        <!-- Examples below show Azure Mobile Services headers -->
        <header>x-zumo-installation-id</header>
        <header>x-zumo-application</header>
        <header>x-zumo-version</header>
        <header>x-zumo-auth</header>
        <header>content-type</header>
        <header>accept</header>
    </allowed-headers>
    <expose-headers>
        <!-- Examples below show Azure Mobile Services headers -->
        <header>x-zumo-installation-id</header>
        <header>x-zumo-application</header>
    </expose-headers>
</cors>

Conteúdos relacionados

Para obter mais informações sobre como trabalhar com políticas, consulte: