Política de CORS

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

O quê

A partilha de recursos de origem cruzada (CORS) é um mecanismo padrão que permite que as chamadas JavaScript XMLHttpRequest (XHR) executadas numa página Web interajam com recursos de domínios não originais. A CORS é uma solução implementada frequentemente para a política de mesma origem aplicada por todos os navegadores.

Por exemplo, se fizer uma chamada XHR à API Twitter a partir de código JavaScript executado no seu navegador, a chamada falha. Isto deve-se ao facto de o domínio que publica a página no seu navegador não ser o mesmo que o domínio que publica a API Twitter. O CORS oferece uma solução para este problema ao permitir que os servidores optem por partilhar recursos de origem cruzada.

Esta política CORS permite que os clientes do Apigee definam políticas CORS para APIs consumidas por aplicações Web.

Esta política é uma política padrão e pode ser implementada em qualquer tipo de ambiente. Para obter informações sobre os tipos de políticas e a disponibilidade com cada tipo de ambiente, consulte Tipos de políticas.

Atenção:

A implementação de uma política CORS pode tornar a política de mesma origem (SOP) menos rígida. Se um programador de proxy definir o cabeçalho Access-Control-Allow-Origin para permitir tudo (*), desativa efetivamente a proteção de mesma origem.

O campo AllowOrigins é um elemento de política obrigatório e o valor predefinido não deve ser definido para permitir tudo (*). Os programadores de políticas devem tomar decisões cautelosas antes de exporem os respetivos recursos.

Exemplos de utilização

Um exemplo de utilização comum de CORS é a funcionalidade Experimentar esta API do SmartDocs do portal do programador.

Para mais informações, consulte o artigo Configurar o proxy da API para suportar o painel Experimentar esta API.

<CORS> elemento

Define a política de CORS.

Valor predefinido	Consulte o separador Política predefinida abaixo
Obrigatório?	Obrigatória
Tipo	Objeto complexo
Elemento principal	N/A
Elementos subordinados	<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 predefinida

O exemplo seguinte mostra as predefinições quando adiciona a política CORS ao seu 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 insere uma nova política CORS na IU do Apigee, o modelo contém marcadores para todas as operações possíveis. Normalmente, seleciona as operações que quer realizar com esta política e remove os restantes elementos secundários. Por exemplo, se quiser especificar os métodos HTTP permitidos para aceder ao recurso, use o elemento <AllowMethods> e remova os outros elementos subordinados da política para a tornar mais legível.

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

Atributo	Predefinição	Obrigatório?	Descrição
name	N/A	Obrigatório	O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hífenes, sublinhados e pontos finais. Este valor não pode exceder 255 carateres. Opcionalmente, use o elemento <DisplayName> para etiquetar a política no editor de proxy da IU de gestão com um nome diferente em linguagem natural.
continueOnError	falso	Opcional	Definido como false para devolver um erro quando uma política falha. Este comportamento é o esperado para a maioria das políticas. Definido como true para que a execução do fluxo continue mesmo depois de uma política falhar. Veja também: As regras de falhas são acionadas APENAS num estado de erro (acerca de continueOnError) Processar falhas no fluxo atual
enabled	verdadeiro	Opcional	Defina como true para aplicar a política. Defina como false para desativar a política. A política não é aplicada, mesmo que permaneça anexada a um fluxo.
async	falso	Descontinuado	Este atributo foi descontinuado.

Cada um dos elementos secundários é descrito nas secções que se seguem.

Exemplos

São fornecidos exemplos para todos os elementos secundários nas secções seguintes.

Referência de elemento secundário

Esta secção descreve os elementos subordinados de <CORS>.

<AllowCredentials>

Indica se o autor da chamada tem autorização para enviar o pedido real (não o preflight) através de credenciais. Traduz-se no cabeçalho Access-Control-Allow-Credentials.

Valor predefinido	Se não for especificado, Access-Control-Allow-Credentials não é definido.
Obrigatório?	Opcional
Tipo	Booleano
Elemento principal	<CORS>
Elementos subordinados	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

Este exemplo define o cabeçalho Access-Control-Allow-Credentials como false. Ou seja, o autor da chamada não tem autorização para enviar o pedido real (não o pedido prévio) com 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 quando pede o recurso. Serializado para o cabeçalho Access-Control-Allow-Headers.

Valor predefinido	Origin, Accept, X-Requested-With, Content-Type, Access-Control-Request-Method, Access-Control-Request-Headers
Obrigatório?	Opcional
Tipo	String, com suporte de modelo de mensagem*
Elemento principal	<CORS>
Elementos subordinados	Nenhum

Sugestão: o Apigee recomenda que adicione, 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 permitidos para aceder ao recurso. O conteúdo vai ser serializado no cabeçalho Access-Control-Allow-Methods.

Valor predefinido	GET, POST, HEAD, OPTIONS
Obrigatório?	Opcional
Tipo	String, com suporte de modelo de mensagem*
Elemento principal	<CORS>
Elementos subordinados	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

Este exemplo especifica os métodos HTTP que têm autorização para aceder ao recurso.

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

Exemplo:
Wildcard

Este exemplo especifica que todos os métodos HTTP têm autorização para aceder ao 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 autorização para aceder ao recurso. Use um asterisco (*) para permitir o acesso a um recurso a partir de qualquer origem. Caso contrário, forneça uma lista de permissões de origens separadas por vírgulas. Se for encontrada uma correspondência, o valor de saída Access-Control-Allow-Origin é definido como a origem fornecida pelo cliente.

Valor predefinido	N/A
Obrigatório?	Obrigatória
Tipo	String, com suporte de modelo de mensagem*
Elemento principal	<CORS>
Elementos subordinados	Nenhum

Sugestão: o Apigee recomenda que adicione, 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 tem autorização para aceder ao recurso.

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

Exemplo:
vários URLs

Este exemplo especifica várias origens que têm autorização para aceder ao 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

Este exemplo especifica uma variável de contexto que representa uma ou mais origens que têm permissão para aceder ao recurso.

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

Exemplo:
Variável de fluxo

Este exemplo especifica uma variável de fluxo que representa uma origem com autorização para aceder ao recurso.

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

Exemplo:
Wildcard

Este exemplo especifica que todas as origens têm autorização para aceder ao recurso.

Nota: também pode definir uma variável de contexto num modelo de mensagem para um asterisco (*).

Aviso: se um programador de proxy definir o cabeçalho Access-Control-Allow-Origin para permitir tudo (*), desativa efetivamente a proteção de mesma origem. A predefinição não deve ser definida para permitir tudo (*). Os programadores de políticas devem tomar decisões cautelosas antes de exporem os respetivos recursos.

<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 aos quais os navegadores têm autorização para aceder ou um asterisco (*) para permitir todos os cabeçalhos HTTP. Serializado no cabeçalho Access-Control-Expose-Headers.

Valor predefinido	Se não for especificado, Access-Control-Expose-Headers não é definido. Os cabeçalhos não simples não são expostos por predefinição.
Obrigatório?	Opcional
Tipo	String, com suporte de modelo de mensagem*
Elemento principal	<CORS>
Elementos subordinados	Nenhum

Sugestão: o Apigee recomenda que adicione, 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 aceder a 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 deve gerar e devolver a resposta de verificação prévia de CORS. Se false, não é enviada nenhuma resposta. Em vez disso, são preenchidas as seguintes variáveis de fluxo:

• 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 predefinido	true
Obrigatório?	Opcional
Tipo	Booleano
Elemento principal	<CORS>
Elementos subordinados	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

Este exemplo especifica que a política deve gerar e devolver a resposta de verificação prévia de 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 é encontrada uma variável não resolvida. Definido como true para ignorar as variáveis não resolvidas e continuar o processamento; caso contrário, false.

Valor predefinido	true
Obrigatório?	Opcional
Tipo	Booleano
Elemento principal	<CORS>
Elementos subordinados	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 é encontrada uma variável não resolvida.

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

<MaxAge>

Especifica durante quanto tempo os resultados de um pedido de pré-voo podem ser colocados em cache em segundos. Um valor de -1 preenche o cabeçalho Access-Control-Max-Age com um valor de -1, que desativa o armazenamento em cache, o que requer uma verificação de pré-voo OPTIONS para todas as chamadas. Isto é definido na especificação Access-Control-Max-Age.

Valor predefinido	1800
Obrigatório?	Opcional
Tipo	Número inteiro
Elemento principal	<CORS>
Elementos subordinados	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

Este exemplo especifica que os resultados de um pedido de pré-voo podem ser colocados em cache durante 3628800 segundos.

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

Exemplo:
No cache

Este exemplo especifica que os resultados de um pedido de verificação prévia não podem ser colocados em cache.

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

Notas de utilização

OPTIONS pedidos

Quando um pedido OPTIONS é recebido e processado pela política de CORS, a execução do fluxo de proxy é transferida diretamente para o PreFlow de resposta do proxy, ignorando completamente os fluxos de pedidos e continua a execução a partir daí. Não é necessário criar uma condição para ignorar o pedido OPTIONS no fluxo de pedidos proxy.

Nas chamadas subsequentes, quando a política CORS é executada, se o MaxAge definido na política não tiver expirado, o fluxo continua normalmente. Durante o fluxo de resposta final, imediatamente antes de "Resposta enviada ao cliente", um passo de execução de CORS especial "CORSResponseOrErrorFlowExecution" define os cabeçalhos de resposta de CORS (Access-Control-Allow-Credentials, Access-Control-Allow-Origin e Access-Control-Expose-Headers) para devolver uma resposta validada por CORS.

Códigos de erro

Esta secção descreve os códigos de falha e as mensagens de erro devolvidas, bem como as variáveis de falha definidas pelo Apigee quando esta política aciona um erro. Estas informações são importantes para saber se estiver a desenvolver regras de falhas para processar falhas. Para saber mais, consulte os artigos O que precisa de saber sobre erros de políticas e Processar falhas.

Erros de tempo de execução

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

Código de falha	Estado de HTTP	Causa
steps.cors.UnresolvedVariable	500	Este erro ocorre se uma variável especificada na política de CORS for: Fora do âmbito (não disponível no fluxo específico onde a política está a ser executada) ou Não é possível resolver (não está definido)

Erros de implementação

Estes erros podem ocorrer quando implementa um proxy que contém esta política.

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

Variáveis de falha

Estas variáveis são definidas quando esta política aciona um erro no tempo de execução. Para mais informações, consulte O que precisa de saber sobre os erros de políticas.

Nota : se <GeneratePreflightResponse> estiver definido como verdadeiro e ocorrer um erro, a política devolve imediatamente uma resposta ao cliente e o fluxo de erros é ignorado. As seguintes variáveis não estão preenchidas:

Variáveis	Onde	Exemplo
fault.name = "FAULT_NAME"	FAULT_NAME é o nome da falha, conforme indicado na tabela Erros de tempo 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 especificado pelo utilizador da política que gerou a falha.	cors.AddCORS.failed = true

Exemplo de resposta de erro

Nota: para o processamento de erros, a prática recomendada é capturar a parte errorcode da resposta de erro. Não confie no texto em faultstring, porque pode mudar.

{
   "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

É adicionado um objeto CorsFlowInfo FlowInfo, que fica disponível para rastreio.

Propriedade	Tipo	Leitura/escrita	Descrição	O âmbito começa
cross_origin_resource_sharing.allow.credentials	Booleano	Leitura/escrita	Valor de <AllowCredentials>	Pedido de proxy
cross_origin_resource_sharing.allow.headers	String	Leitura/escrita	Valor de <AllowHeaders>	Pedido de proxy
cross_origin_resource_sharing.allow.methods	String	Leitura/escrita	Valor de <AllowMethods>	Pedido de proxy
cross_origin_resource_sharing.allow.origin	String	Leitura/escrita	A origem do pedido permitida, vazia se não estiver na lista de autorizações	Pedido de proxy
cross_origin_resource_sharing.allow.origins.list	String	Leitura/escrita	Valor de <AllowOrigins>	Pedido de proxy
cross_origin_resource_sharing.expose.headers	String	Leitura/escrita	Valor de <ExposeHeaders>	Pedido de proxy
cross_origin_resource_sharing.max.age	Número inteiro	Leitura/escrita	Valor de <MaxAge>	Pedido de proxy
cross_origin_resource_sharing.preflight.accepted	Booleano	Leitura/escrita	Indica se o pedido de verificação prévia é aceite	Pedido de proxy
cross_origin_resource_sharing.request.headers	String	Leitura/escrita	O valor do cabeçalho Access-Control-Request-Headers do pedido	Pedido de proxy
cross_origin_resource_sharing.request.method	String	Leitura/escrita	O valor do cabeçalho Access-Control-Request-Method do pedido	Pedido de proxy
cross_origin_resource_sharing.request.origin	String	Leitura/escrita	Igual a request.header.origin	Pedido de proxy
cross_origin_resource_sharing.request.type	String	Leitura/escrita	Tipo de pedido CORS. Valores possíveis: REAL: um pedido que não é um pedido de verificação prévia PRE_FLIGHT: um pedido de verificação prévia	Pedido de proxy