Política de CORS

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

Confira a documentação da Apigee Edge.

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. Para informações sobre os tipos de políticas e a disponibilidade de cada tipo de ambiente, consulte Tipos de políticas.

Atenção:

A implementação de uma política de CORS pode relaxar a política de mesma origem (SOP). Se um desenvolvedor de proxy definir o cabeçalho Access-Control-Allow-Origin para permitir todos (*), ele desativará efetivamente a proteção de mesma origem.

O campo AllowOrigins é um elemento de política obrigatório, e o padrão não pode ser definido para permitir todos (*). Os desenvolvedores de políticas precisam tomar decisões cautelosas antes de expor os recursos.

Casos de uso

Um caso de uso comum do CORS é o recurso Try this API do portal SmartDoc do portal do desenvolvedor.

Para mais informações, consulte Como configurar seu proxy de API para ser compatível com o painel "Testar esta API".

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: As regras de falha são acionadas SOMENTE em um estado de erro (sobre continueOnError) Como corrigir falhas no fluxo atual
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	Booleano
Elemento pai	<CORS>
Elemento filho	Nenhum

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

This example sets the Access-Control-Allow-Credentials header to false. That is, the caller is not allowed to send the actual request (not the preflight) using credentials.

<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

Dica:a Apigee recomenda adicionar no máximo 50 valores a <AllowHeaders>.

* 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

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

This example specifies the HTTP methods that are allowed to access the resource.

<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

Dica:a Apigee recomenda adicionar no máximo 50 valores a <AllowOrigins>.

* 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

This example specifies multiple origins that are allowed to access the resource.

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

Exemplo:
variável de contexto

This example specifies a context variable that represents one or more origins that are allowed to access the resource.

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

Exemplo:
variável de fluxo

This example specifies a flow variable that represents one origin that is allowed to access the resource.

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

Exemplo:
caractere curinga

This example specifies that all origins are allowed to access the resource.

Note: You can also set a context variable in a message template to an asterisk (*).

Caution: If a proxy developer sets the Access-Control-Allow-Origin header to allow all (*), it effectively disables the same-origin protection. The default should not be set to allow all (*). Policy developers should make cautious decisions before exposing their resources.

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

<DisplayName>

Use em conjunto com o atributo name para etiquetar a política no editor de proxy da IU de gestão com um nome diferente e mais natural.

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

Valor predefinido	N/A
Obrigatório?	Opcional. Se omitir <DisplayName>, é usado o valor do atributo name da política.
Tipo	String
Elemento principal	<PolicyElement>
Elementos subordinados	Nenhum

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 nem elementos subordinados.

<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

Dica:a Apigee recomenda adicionar no máximo 50 valores a <ExposeHeaders>.

* 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	Booleano
Elemento pai	<CORS>
Elemento filho	Nenhum

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

This example specifies that the policy should generate and return the CORS preflight response.

<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	Booleano
Elemento pai	<CORS>
Elemento filho	Nenhum

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	Número inteiro
Elemento pai	<CORS>
Elemento filho	Nenhum

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

This example specifies that the results of a preflight request can be cached for 3628800 seconds.

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

Exemplo:
Sem cache

This example specifies that the results of a preflight request cannot be cached.

<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

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Cause
steps.cors.UnresolvedVariable	500	This error occurs if a variable specified in the CORS policy is either: Out of scope (not available in the specific flow where the policy is being executed) or Can't be resolved (is not defined)

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name	Cause
InvalidMaxAge	MaxAge is not number
MissingAllowOrigins	AllowOrigins is not specified
InvalidHTTPMethods	One of the methods in AllowMethods is not valid
AllowHeadersSizeTooLarge	The string size in AllowHeaders is too large.
ExposeHeadersSizeTooLarge	The string size in ExposeHeaders is too large.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Note : If <GeneratePreflightResponse> is set to true and an error occurs, the policy returns a response to the client immediately and the error flow is skipped. The following variables are not populated:

Variables	Where	Example
fault.name = "FAULT_NAME"	FAULT_NAME is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	fault.name Matches "UnresolveVariable"
cors.POLICY_NAME.failed	POLICY_NAME is the user-specified name of the policy that threw the fault.	cors.AddCORS.failed = true

Example error response

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

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

Example fault rule

<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	Número 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