CORS

  • Artigo

APLICA-SE A: todas as camadas do Gerenciamento de API

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

Observação

Defina os elementos da política e os elementos filho na ordem fornecida na declaração da política. Para ajudá-lo a configurar essa política, o portal fornece um editor guiado baseado em formulário. Saiba mais sobre como definir e editar as 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

Name Descrição Obrigatório Padrão
allow-credentials O cabeçalho Access-Control-Allow-Credentials na resposta preliminar será definido com o valor desse atributo e afetará a capacidade do cliente para enviar credenciais nas solicitações entre domínios. Expressões de política são permitidas. Não false
terminate-unmatched-request Controla o processamento de solicitações entre origens que não correspondem às configurações de política. Expressões de política são permitidas.

Quando OPTIONS a solicitação é processada como uma solicitação de pré-voo e o cabeçalho Origin 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 for definido como false, verifique a entrada para outras políticas cors no escopo que sejam filhos diretos do elemento de entrada e aplique-as. Se nenhuma política de cors for encontrada, encerre a solicitação com uma resposta 200 OK vazia.

Quando GET ou HEAD a solicitação inclui o cabeçalho Origin (e, portanto, é processado como uma solicitação de origem cruzada simples) 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 Obrigatório Padrão
allowed-origins Contém elementos origin que descrevem as origens permitidas para solicitações entre domínios. allowed-origins pode conter um único elemento origin que especifica * para permitir qualquer origem, ou um ou mais elementos origin que contêm uma URI. Sim N/D
allowed-methods Esse elemento é necessário se métodos diferentes de GET ou POST forem permitidos. Contém elementos method que especificam os verbos HTTP compatíveis. O valor * indica todos os métodos. No Se esta seção não estiver presente, há suporte para GET e POST.
allowed-headers Esse elemento contém elementos header que especificam os nomes dos cabeçalhos que podem ser incluídos na solicitação. Sim N/D
expose-headers Esse elemento contém elementos header que especificam os nomes dos cabeçalhos que ficarão acessíveis para o cliente. Não N/D

Cuidado

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

elementos allowed-origins

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

atributos allowed-methods

Nome Descrição Obrigatório Padrão
preflight-result-max-age O cabeçalho Access-Control-Max-Age na resposta pré-voo será definido como o valor desse atributo e afetará a capacidade do agente do usuário de colocar em cache a resposta preliminar. Expressões de política são permitidas. Não 0

elementos allowed-methods

Nome Descrição Obrigatório Padrão
method Especifica um verbo HTTP. Expressões de política são permitidas. Pelo menos um elemento method é necessário se a seção allowed-methods estiver presente. N/D

elementos allowed-headers

Nome Descrição Obrigatório Padrão
header Especifica um nome de cabeçalho. Pelo menos um elemento header é necessário em allowed-headers se esta seção estiver presente. N/D

elementos expose-headers

Nome Descrição Obrigatório Padrão
header Especifica um nome de cabeçalho. Pelo menos um elemento header é necessário em expose-headers se esta seção estiver presente. N/D

Uso

Observações de uso

  • Você pode configurar a política cors em mais de um escopo (por exemplo, no escopo do produto e no escopo global). Verifique se o elemento base está configurado nos escopos de operação, API e produto para herdar as políticas necessárias nos escopos pai.
  • Somente a política cors é avaliada na solicitação OPTIONS durante o pré-voo. As políticas configuradas restantes são avaliadas na solicitação aprovada.
  • Essa política só pode ser usada uma vez em uma seção de política.

Sobre o CORS

O CORS é um padrão baseado em cabeçalho HTTP que permite que um navegador e um servidor interajam e determina e solicitações entre origens específicas devem ou não ser aceitas (chamadas XMLHttpRequest feitas por meio de JavaScript em uma página da Web para outros domínios). Isso permite maior flexibilidade do que permitir somente solicitações com a mesma origem, mas é mais seguro do que permitir todas as solicitações entre origens.

O CORS especifica dois tipos de solicitações entre origens:

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

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

Cenários de política cors

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

  • Habilite o console de teste interativo no portal do desenvolvedor. Consulte a documentação do portal do desenvolvedor para obter detalhes.

    Observação

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

  • Habilite o Gerenciamento de API a responder a solicitações de pré-voo ou passar por solicitações simples do CORS quando os back-ends não fornecerem seu próprio suporte ao CORS.

    Observação

    Se a solicitação corresponder a uma operação com um método OPTIONS definido na API, a lógica de processamento de solicitação preliminar associada à política cors não será executada. Portanto, essas operações podem ser usadas para implementar a lógica de processamento de pré-voo personalizada – por exemplo, para aplicar a política cors somente em determinadas condições.

Problemas de configuração comuns

  • Chave de assinatura no cabeçalho – se você configurar a política cors no escopo do produto e sua API usar a 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 alternativa, modifique as solicitações para incluir uma chave de assinatura como um parâmetro de consulta.
  • API com controle de versão de cabeçalho – se você configurar a política cors 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. Talvez seja necessário configurar um método de controle de versão alternativo, como um caminho ou parâmetro de consulta.
  • Ordem de política – você poderá ter um comportamento inesperado se a política cors 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 de política em cada escopo. Geralmente, somente a primeira política cors é aplicada.
  • Resposta 200 OK vazia – em algumas configurações de política, determinadas solicitações entre origens são concluídas com uma resposta 200 OK vazia. Essa resposta é esperada quando terminate-unmatched-request é definido como seu valor padrão de true e uma solicitação de entrada tem um cabeçalho Origin que não corresponde a uma origem permitida configurada na política cors.

Exemplo

Este exemplo demonstra como dar suporte a solicitações da versão pré-piloto, como as com cabeçalhos personalizados ou métodos diferentes de GET e POST. Para oferecer suporte a outros cabeçalhos personalizados e verbos HTTP, use as seções allowed-methods 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údo relacionado

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