Política de CORS

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Ícone da política

O que é?

O compartilhamento de recursos entre origens (CORS, na sigla em inglês) é um mecanismo padrão que permite que chamadas JavaScript XMLHttpRequest (XHR) executadas em uma página da Web interajam com recursos de domínios que não são de origem. O CORS é uma solução comumente implementada na política de mesma origem que é aplicada por todos os navegadores.

Por exemplo, se você fizer uma chamada XHR para a API Twitter a partir do código JavaScript em execução no seu navegador, a chamada falhará. Isso ocorre porque o domínio que veicula a página para o navegador não é o mesmo que usa a API Twitter. O CORS oferece uma solução para esse problema permitindo que os servidores optem por permitir o compartilhamento de recursos entre origens.

Essa política de CORS permite que os clientes da Apigee definam políticas de CORS para APIs consumidas por aplicativos da Web.

Esta é uma política padrão e pode ser implantada em qualquer tipo de ambiente. Nem todos os usuários têm necessidade de saber sobre os tipos de política e ambiente. Para informações sobre os tipos de políticas e a disponibilidade de cada tipo de ambiente, consulte Tipos de políticas.

Elemento <CORS>

Define a política de CORS.

Valor padrão Consulte a guia Política padrão a seguir
Obrigatório? Obrigatório
Tipo Objeto complexo
Elemento pai N/A
Elemento filho <AllowCredentials>
<AllowHeaders>
<AllowMethods>
<AllowOrigins>
<DisplayName>
<ExposeHeaders>
<GeneratePreflightResponse>
<IgnoreUnresolvedVariables>
<MaxAge>

O elemento <CORS> usa a seguinte sintaxe:

Sintaxe

O elemento <CORS> usa a seguinte sintaxe:


<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <DisplayName>DISPLAY_NAME</DisplayName>
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <AllowMethods>[GET, PUT, POST, DELETE, ...|*]</AllowMethods>
  <AllowHeaders>[origin, x-requested-with, accept, content-type, ...]</AllowHeaders>
  <ExposeHeaders>[X-CUSTOM-HEADER-A, X-CUSTOM-HEADER-B, ... | *]</ExposeHeaders>
  <MaxAge>[integer|-1]</MaxAge>
  <AllowCredentials>[false|true]</AllowCredentials>
  <GeneratePreflightResponse>[false|true]</GeneratePreflightResponse>
  <IgnoreUnresolvedVariables>[false|true]</IgnoreUnresolvedVariables>
</CORS>

política_padrão

O exemplo a seguir mostra as configurações padrão quando você adiciona a política de CORS ao fluxo na IU do Edge:

<CORS continueOnError="false" enabled="true" name="add-cors">
    <DisplayName>Add CORS</DisplayName>
    <AllowOrigins>{request.header.origin}</AllowOrigins>
    <AllowMethods>GET, PUT, POST, DELETE</AllowMethods>
    <AllowHeaders>origin, x-requested-with, accept, content-type</AllowHeaders>
    <ExposeHeaders>*</ExposeHeaders>
    <MaxAge>3628800</MaxAge>
    <AllowCredentials>false</AllowCredentials>
    <GeneratePreflightResponse>true</GeneratePreflightResponse>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</CORS>

Quando você insere uma nova política CORS na IU do Apigee, o modelo contém stubs para todas as operações possíveis. Normalmente, você seleciona quais operações quer executar com essa política e remove o restante dos elementos filhos. Por exemplo, se você quiser especificar os métodos HTTP com permissão para acessar o recurso, use o elemento <AllowMethods> e remova os outros elementos filhos da política para torná-la mais seja legível.

Este elemento tem os seguintes atributos comuns a todas as políticas:

Atributo Padrão Obrigatório? Descrição
name N/A Valor

O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hifens, sublinhados e pontos. Esse valor não pode exceder 255 caracteres.

Opcionalmente, use o elemento <DisplayName> para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.

continueOnError falso Opcional Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado para a maioria das políticas. Defina como true para que a execução do fluxo continue, mesmo depois que uma política falhar. Consulte também:
enabled true Opcional Defina como true para aplicar a política. Defina como false para desativar a política. A política não será aplicada mesmo que permaneça vinculada a um fluxo.
async   falso Obsoleto Esse atributo está obsoleto.

Cada um desses elementos filhos é descrito nas seções a seguir.

Exemplos

Veja exemplos para todos os elementos filhos nas seções a seguir.

Referência a elementos filhos

Esta seção descreve os elementos filhos de <CORS>.

<AllowCredentials>

Indica se o autor da chamada tem permissão para enviar a solicitação real (não a simulação) usando credenciais. Traduz para o cabeçalho Access-Control-Allow-Credentials.

Valor padrão Se não for especificado, Access-Control-Allow-Credentials não será definido.
Obrigatório? Opcional
Tipo Booleanos
Elemento pai <CORS>
Elemento filho Nenhuma

O elemento <AllowCredentials> usa a seguinte sintaxe:

Sintaxe

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <AllowCredentials>[false|true]</AllowCredentials>
</CORS>
      

Exemplo

Neste exemplo, definimos o cabeçalho Access-Control-Allow-Credentials como false. Ou seja, o autor da chamada não tem permissão para enviar a solicitação real (não a simulação) usando credenciais.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <AllowCredentials>false</AllowCredentials>
</CORS>

<AllowHeaders>

Lista de cabeçalhos HTTP que podem ser usados ao solicitar o recurso. Serializada para o cabeçalho Access-Control-Allow-Headers.

Valor padrão Origin, Accept, X-Requested-With, Content-Type, Access-Control-Request-Method, Access-Control-Request-Headers
Obrigatório? Opcional
Tipo String, compatível com modelo de mensagem*
Elemento pai <CORS>
Elemento filho Nenhum

* Para mais informações, consulte O que é um modelo de mensagem?

O elemento <AllowHeaders> usa a seguinte sintaxe:

Sintaxe

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <AllowHeaders>[origin, x-requested-with, accept, content-type, ...]</AllowHeaders>
</CORS>

Exemplo

CORS AllowOrigins example

This example specifies the HTTP headers that can be used when requesting the resource.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <AllowHeaders>origin, x-requested-with, accept, content-type</AllowHeaders>
</CORS>

<AllowMethods>

Lista de métodos HTTP com permissão para acessar o recurso. O conteúdo será serializado no cabeçalho Access-Control-Allow-Methods.

Valor padrão GET, POST, HEAD, OPTIONS
Obrigatório? Opcional
Tipo String, compatível com modelo de mensagem*
Elemento pai <CORS>
Elemento filho Nenhum

* Para mais informações, consulte O que é um modelo de mensagem?

O elemento <AllowMethods> usa a seguinte sintaxe:

Sintaxe

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <AllowMethods>[GET, PUT, POST, DELETE, ...|*]</AllowMethods>
</CORS>

Exemplo:
lista

Neste exemplo, são especificados os métodos HTTP que têm permissão para acessar o recurso.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <AllowMethods>GET, PUT, POST, DELETE</AllowMethods>
</CORS>

Exemplo:
caractere curinga

Este exemplo especifica que todos os métodos HTTP têm permissão para acessar o recurso.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <AllowMethods>*</AllowMethods>
</CORS>

<AllowOrigins>

Uma lista de origens que têm permissão para acessar o recurso. Use um asterisco (*) para ativar o acesso a um recurso de qualquer origem. Caso contrário, forneça uma lista de permissões de origens separadas por vírgulas. Se uma correspondência for encontrada, o Access-Control-Allow-Origin de saída será definido como a origem fornecida pelo cliente.

Valor padrão N/A
Obrigatório? Obrigatório
Tipo String, compatível com modelo de mensagem*
Elemento pai <CORS>
Elemento filho Nenhum

* Para mais informações, consulte O que é um modelo de mensagem?

O elemento <AllowOrigins> usa a seguinte sintaxe:

Sintaxe

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
</CORS>

Exemplo:
URL único

Este exemplo especifica uma única origem de URL que pode acessar o recurso.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>https://www.w3.org</AllowOrigins>
</CORS>

Exemplo:
vários URLs

Neste exemplo, são especificadas várias origens que têm permissão para acessar o recurso.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>https://www.w3.org, https://www.apache.org</AllowOrigins>
</CORS>

Exemplo:
variável de contexto

Neste exemplo, especificamos uma variável de contexto que representa uma ou mais origens com permissão para acessar o recurso.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{origins.list}</AllowOrigins>
</CORS>

Exemplo:
variável de fluxo

Neste exemplo, especificamos uma variável de fluxo que representa uma origem com permissão para acessar o recurso.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
</CORS>

Exemplo:
caractere curinga

Este exemplo especifica que todas as origens têm permissão para acessar o recurso.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>*</AllowOrigins>
</CORS>

<DisplayName>

Use além do atributo name para rotular a política no editor de proxy da IU de gerenciamento com um nome de som diferente e mais natural.

O elemento <DisplayName> é comum a todas as políticas.

Valor padrão N/A
Obrigatório? Opcional. Se você omitir <DisplayName>, o valor do atributo name da política será usado
Tipo String
Elemento pai <PolicyElement>
Elemento filho Nenhuma

O elemento <DisplayName> usa a seguinte sintaxe:

Sintaxe

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Exemplo

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

O elemento <DisplayName> não tem atributos ou elementos filhos.

<ExposeHeaders>

Uma lista de cabeçalhos HTTP que os navegadores podem acessar ou um asterisco (*) para permitir todos os cabeçalhos HTTP. Serializada no cabeçalho Access-Control-Expose-Headers.

Valor padrão Se não for especificado, Access-Control-Expose-Headers não será definido. Cabeçalhos não simples não são expostos por padrão.
Obrigatório? Opcional
Tipo String, compatível com modelo de mensagem*
Elemento pai <CORS>
Elemento filho Nenhum

* Para mais informações, consulte O que é um modelo de mensagem?

O elemento <ExposeHeaders> usa a seguinte sintaxe:

Sintaxe

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <ExposeHeaders>[X-CUSTOM-HEADER-A, X-CUSTOM-HEADER-B, ... | *]</ExposeHeaders>
</CORS>

Exemplo

Este exemplo especifica que os navegadores podem acessar todos os cabeçalhos HTTP.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <ExposeHeaders>*</ExposeHeaders>
</CORS>

<GeneratePreflightResponse>

Indique se a política precisa gerar e retornar a resposta de simulação do CORS. Se false, nenhuma resposta será enviada. Em vez disso, as seguintes variáveis de fluxo são preenchidas:

  • cross_origin_resource_sharing.allow.credentials
  • cross_origin_resource_sharing.allow.headers
  • cross_origin_resource_sharing.allow.methods
  • cross_origin_resource_sharing.allow.origin
  • cross_origin_resource_sharing.allow.origins.list
  • cross_origin_resource_sharing.expose.headers
  • cross_origin_resource_sharing.max.age
  • cross_origin_resource_sharing.preflight.accepted
  • cross_origin_resource_sharing.request.headers
  • cross_origin_resource_sharing.request.method
  • cross_origin_resource_sharing.request.origin
  • cross_origin_resource_sharing.request.type
Valor padrão true
Obrigatório? Opcional
Tipo Booleanos
Elemento pai <CORS>
Elemento filho Nenhuma

O elemento <GeneratePreflightResponse> usa a seguinte sintaxe:

Sintaxe

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <GeneratePreflightResponse>[false|true]</GeneratePreflightResponse>
  <GeneratePreflightResponse>[false|true]</GeneratePreflightResponse>
</CORS>

Exemplo

Este exemplo especifica que a política precisa gerar e retornar a resposta de simulação do CORS.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <GeneratePreflightResponse>true</GeneratePreflightResponse>
</CORS>

<IgnoreUnresolvedVariables>

Determina se o processamento é interrompido quando uma variável não resolvida é encontrada. Defina como true para ignorar variáveis não resolvidas e continuar o processamento. Caso contrário, false.

Valor padrão true
Obrigatório? Opcional
Tipo Booleanos
Elemento pai <CORS>
Elemento filho Nenhuma

O elemento <IgnoreUnresolvedVariables> usa a seguinte sintaxe:

Sintaxe

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <IgnoreUnresolvedVariables>[false|true]</IgnoreUnresolvedVariables>
</CORS>

Exemplo

Este exemplo especifica que o processamento continua quando uma variável não resolvida é encontrada.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</CORS>

<MaxAge>

Especifica por quanto tempo os resultados de uma solicitação de simulação podem ser armazenados em cache em segundos. Um valor de -1 preenche o cabeçalho Access-Control-Max-Age com um valor de -1, o que desativa o armazenamento em cache, exigindo uma simulação OPTIONS verificar todas as chamadas. Isso é definido na especificação Access-Control-Max-Age.

Valor padrão 1800
Obrigatório? Opcional
Tipo Inteiro
Elemento pai <CORS>
Elemento filho Nenhuma

O elemento <MaxAge> usa a seguinte sintaxe:

Sintaxe

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <MaxAge>[integer|-1]</MaxAge>
</CORS>

Exemplo:
Cache

Este exemplo especifica que os resultados de uma solicitação de simulação podem ser armazenados em cache por 3628800 segundos.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <MaxAge>3628800</MaxAge>
</CORS>

Exemplo:
Sem cache

Este exemplo especifica que os resultados de uma solicitação de simulação não podem ser armazenados em cache.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <MaxAge>-1</MaxAge>
</CORS>

Observações sobre uso

Solicitações OPTIONS

Quando uma solicitação OPTIONS é recebida e processada pela política de CORS, a execução do fluxo do proxy é transferida diretamente para o pré-fluxo de resposta do proxy, ignorando completamente os fluxos de solicitação e continua a partir daí. Não é necessário criar uma condição para ignorar a solicitação OPTIONS no fluxo de solicitações do proxy.

Nas chamadas subsequentes, quando a política de CORS for executada, se o MaxAge definido na política não tiver expirado, o fluxo continuará normalmente. Durante o fluxo de resposta final, logo antes de "Resposta enviada ao cliente", uma etapa especial de execução do CORS "CORSResponseOrErrorFlowExecution" define os cabeçalhos de resposta do CORS (Access-Control-Allow-Credentials, Access-Control-Allow-Origin e Access-Control-Expose-Headers) para retornar uma resposta validada pelo CORS.

Códigos de erro

Nesta seção, descrevemos os códigos de falha e as mensagens de erro retornadas e as variáveis com falha definidas pela Apigee quando essa política aciona um erro. Essas informações são importantes para saber se você está desenvolvendo regras de falha para lidar com falhas. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.

Erros de execução

Esses erros podem ocorrer quando a política é executada.

Código de falha Status HTTP Causa
steps.cors.UnresolvedVariable 500 Esse erro ocorrerá se uma variável especificada na política CORS:
  • Fora do escopo (não disponível no fluxo específico em que a política está sendo executada)
  • ou

  • Não é possível resolver (não está definida)

Erros na implantação

Esses erros podem ocorrer quando você implanta um proxy que contém esta política.

Nome do erro Causa
InvalidMaxAge MaxAge não é um número
MissingAllowOrigins AllowOrigins não especificado
InvalidHTTPMethods Um dos métodos em AllowMethods não é válido
AllowHeadersSizeTooLarge O tamanho da string em AllowHeaders é muito grande.
ExposeHeadersSizeTooLarge O tamanho da string em ExposeHeaders é muito grande.

Variáveis de falha

Essas variáveis são definidas quando essa política aciona um erro no ambiente de execução. Para mais informações, consulte O que você precisa saber sobre erros de política.

Variáveis Onde Exemplo
fault.name = "FAULT_NAME" FAULT_NAME é o nome da falha, conforme listado na tabela Erros de ambiente de execução acima. O nome da falha é a última parte do código de falha. fault.name Matches "UnresolveVariable"
cors.POLICY_NAME.failed POLICY_NAME é o nome da política especificada pelo usuário que gerou a falha. cors.AddCORS.failed = true

Exemplo de resposta de erro

{
   "fault":{
      "detail":{
         "errorcode":"steps.cors.UnresolvedVariable"
      },
      "faultstring":"CORS[AddCORS]: unable to resolve variable wrong.var"
   }
}

Exemplo de regra de falha

<FaultRule name="Add CORS Fault">
    <Step>
        <Name>Add-CORSCustomUnresolvedVariableErrorResponse</Name>
        <Condition>(fault.name Matches "UnresolvedVariable") </Condition>
    </Step>
    <Condition>(cors.Add-CORS.failed = true) </Condition>
</FaultRule>

Variáveis de fluxo

Um objeto CorsFlowInfo FlowInfo será adicionado e ficará disponível para rastreamento.

Propriedade Tipo Leitura/gravação Descrição O escopo começa
cross_origin_resource_sharing.allow.credentials Booleano Leitura/gravação Valor de <AllowCredentials> Solicitação de proxy
cross_origin_resource_sharing.allow.headers String Leitura/gravação Valor de <AllowHeaders> Solicitação de proxy
cross_origin_resource_sharing.allow.methods String Leitura/gravação Valor de <AllowMethods> Solicitação de proxy
cross_origin_resource_sharing.allow.origin String Leitura/gravação A origem da solicitação permitida, vazia se não estiver na lista de permissões Solicitação de proxy
cross_origin_resource_sharing.allow.origins.list String Leitura/gravação Valor de <AllowOrigins> Solicitação de proxy
cross_origin_resource_sharing.expose.headers String Leitura/gravação Valor de <ExposeHeaders> Solicitação de proxy
cross_origin_resource_sharing.max.age Inteiro Leitura/gravação Valor de <MaxAge> Solicitação de proxy
cross_origin_resource_sharing.preflight.accepted Booleano Leitura/gravação Indica se a solicitação de simulação é aceita. Solicitação de proxy
cross_origin_resource_sharing.request.headers String Leitura/gravação O valor do cabeçalho Access-Control-Request-Headers da solicitação Solicitação de proxy
cross_origin_resource_sharing.request.method String Leitura/gravação O valor do cabeçalho Access-Control-Request-Method da solicitação Solicitação de proxy
cross_origin_resource_sharing.request.origin String Leitura/gravação O mesmo que request.header.origin Solicitação de proxy
cross_origin_resource_sharing.request.type String Leitura/gravação

Tipo de solicitação de CORS. Valores possíveis:

  • REAL: uma solicitação que não é de simulação
  • PRE_FLIGHT: uma solicitação de simulação
Solicitação de proxy