Policy CORS

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Cosa

La condivisione delle risorse tra origini (CORS) è un meccanismo standard che consente alle chiamate JavaScript XMLHttpRequest (XHR) eseguite in una pagina web di interagire con risorse di domini non di origine. CORS è una soluzione comunemente implementata per i criteri della stessa origine applicati da tutti i browser.

Ad esempio, se effettui una chiamata XHR all'API Twitter dal codice JavaScript eseguito nel tuo browser, la chiamata non andrà a buon fine. Questo perché il dominio che pubblica la pagina nel tuo browser non è lo stesso che pubblica l'API Twitter. CORS fornisce una soluzione a questo problema consentendo ai server di attivare la condivisione delle risorse tra origini.

Questa policy CORS consente ai clienti Apigee di impostare policy CORS per le API utilizzate dalle applicazioni web.

Questa policy è una policy standard e può essere implementata in qualsiasi tipo di ambiente. Per informazioni sui tipi di criteri e sulla disponibilità per ogni tipo di ambiente, consulta Tipi di criteri.

Attenzione:

L'implementazione di un criterio CORS può allentare il criterio della stessa origine (SOP). Se uno sviluppatore proxy imposta l'intestazione Access-Control-Allow-Origin per consentire tutto (*), disattiva di fatto la protezione same-origin.

Il campo AllowOrigins è un elemento obbligatorio delle norme e il valore predefinito non deve essere impostato per consentire tutto (*). Gli sviluppatori di norme devono prendere decisioni prudenti prima di esporre le proprie risorse.

Casi d'uso

Un caso d'uso comune di CORS è la funzionalità Prova questa API di SmartDocs del portale per gli sviluppatori.

Per maggiori informazioni, vedi Configurazione del proxy API per supportare il riquadro Prova questa API.

Elemento <CORS>

Definisce il criterio CORS.

Valore predefinito	Consulta la scheda Policy predefinita di seguito.
Obbligatorio?	Obbligatorio
Tipo	Oggetto complesso
Elemento principale	N/D
Elementi secondari	<AllowCredentials> <AllowHeaders> <AllowMethods> <AllowOrigins> <DisplayName> <ExposeHeaders> <GeneratePreflightResponse> <IgnoreUnresolvedVariables> <MaxAge>

L'elemento <CORS> utilizza la seguente sintassi:

Sintassi

L'elemento <CORS> utilizza la seguente sintassi:

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

Policy predefinita

L'esempio seguente mostra le impostazioni predefinite quando aggiungi la policy CORS al tuo flusso nell'interfaccia utente 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 inserisci una nuova policy CORS nell'interfaccia utente Apigee, il modello contiene stub per tutte le operazioni possibili. In genere, selezioni le operazioni che vuoi eseguire con questo criterio e rimuovi il resto degli elementi secondari. Ad esempio, se vuoi specificare i metodi HTTP consentiti per accedere alla risorsa, utilizza l'elemento <AllowMethods> e rimuovi gli altri elementi secondari dalla policy per renderla più leggibile.

Questo elemento ha i seguenti attributi comuni a tutti i criteri:

Attributo	Predefinito	Obbligatorio?	Descrizione
name	N/D	Obbligatorio	Il nome interno del criterio. Il valore dell'attributo name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri. Se vuoi, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.
continueOnError	falso	Facoltativo	Imposta su false per restituire un errore quando un criterio non va a buon fine. Questo è un comportamento previsto per la maggior parte dei criteri. Imposta su true per continuare l'esecuzione del flusso anche dopo un fallimento del criterio. Vedi anche: Le regole di errore vengono attivate SOLO in uno stato di errore (informazioni su continueOnError) Gestione degli errori all'interno del flusso corrente
enabled	true	Facoltativo	Imposta su true per applicare il criterio. Imposta su false per disattivare il criterio. Il criterio non verrà applicato anche se rimane collegato a un flusso.
async	falso	Ritirato	Questo attributo è stato ritirato.

Ognuno degli elementi secondari è descritto nelle sezioni seguenti.

Esempi

Nelle sezioni seguenti sono forniti esempi per tutti gli elementi secondari.

Riferimento all'elemento secondario

Questa sezione descrive gli elementi secondari di <CORS>.

<AllowCredentials>

Indica se al chiamante è consentito inviare la richiesta effettiva (non la preflight) utilizzando le credenziali. Si traduce nell'intestazione Access-Control-Allow-Credentials.

Valore predefinito	Se non specificato, Access-Control-Allow-Credentials non verrà impostato.
Obbligatorio?	Facoltativo
Tipo	Booleano
Elemento principale	<CORS>
Elementi secondari	Nessuno

L'elemento <AllowCredentials> utilizza la seguente sintassi:

Sintassi

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

Esempio

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>

Elenco delle intestazioni HTTP che possono essere utilizzate durante la richiesta della risorsa. Serializzato nell'intestazione Access-Control-Allow-Headers.

Valore predefinito	Origin, Accept, X-Requested-With, Content-Type, Access-Control-Request-Method, Access-Control-Request-Headers
Obbligatorio?	Facoltativo
Tipo	Stringa, con supporto del modello di messaggio*
Elemento principale	<CORS>
Elementi secondari	Nessuno

Suggerimento:Apigee consiglia di aggiungere non più di 50 valori a <AllowHeaders>.

* Per saperne di più, vedi Che cos'è un modello di messaggio?

L'elemento <AllowHeaders> utilizza la seguente sintassi:

Sintassi

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

Esempio

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>

Elenco dei metodi HTTP consentiti per accedere alla risorsa. I contenuti verranno serializzati nell'intestazione Access-Control-Allow-Methods.

Valore predefinito	GET, POST, HEAD, OPTIONS
Obbligatorio?	Facoltativo
Tipo	Stringa, con supporto del modello di messaggio*
Elemento principale	<CORS>
Elementi secondari	Nessuno

* Per saperne di più, vedi Che cos'è un modello di messaggio?

L'elemento <AllowMethods> utilizza la seguente sintassi:

Sintassi

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

Esempio:
List

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>

Esempio:
Carattere jolly

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

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

<AllowOrigins>

Un elenco di origini autorizzate ad accedere alla risorsa. Utilizza un asterisco (*) per abilitare l'accesso a una risorsa da qualsiasi origine. In caso contrario, fornisci una lista consentita di origini separate da virgole. Se viene trovata una corrispondenza, l'Access-Control-Allow-Origin in uscita viene impostato sull'origine fornita dal client.

Valore predefinito	N/D
Obbligatorio?	Obbligatorio
Tipo	Stringa, con supporto del modello di messaggio*
Elemento principale	<CORS>
Elementi secondari	Nessuno

Suggerimento:Apigee consiglia di aggiungere non più di 50 valori a <AllowOrigins>.

* Per saperne di più, vedi Che cos'è un modello di messaggio?

L'elemento <AllowOrigins> utilizza la seguente sintassi:

Sintassi

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

Esempio:
URL singolo

Questo esempio specifica una singola origine URL autorizzata ad accedere alla risorsa.

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

Esempio:
più URL

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>

Esempio:
Variabile di contesto

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>

Esempio:
Variabile di flusso

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>

Esempio:
Carattere jolly

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 in addition to the name attribute to label the policy in the management UI proxy editor with a different, more natural-sounding name.

The <DisplayName> element is common to all policies.

Default Value	N/A
Required?	Optional. If you omit <DisplayName>, the value of the policy's name attribute is used.
Type	String
Parent Element	<PolicyElement>
Child Elements	None

The <DisplayName> element uses the following syntax:

Syntax

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

Example

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

The <DisplayName> element has no attributes or child elements.

<ExposeHeaders>

Un elenco di intestazioni HTTP a cui i browser possono accedere o un asterisco (*) per consentire tutte le intestazioni HTTP. Serialized nell'intestazione Access-Control-Expose-Headers.

Valore predefinito	Se non specificato, Access-Control-Expose-Headers non verrà impostato. Le intestazioni non semplici non vengono esposte per impostazione predefinita.
Obbligatorio?	Facoltativo
Tipo	Stringa, con supporto del modello di messaggio*
Elemento principale	<CORS>
Elementi secondari	Nessuno

Suggerimento:Apigee consiglia di aggiungere non più di 50 valori a <ExposeHeaders>.

* Per saperne di più, vedi Che cos'è un modello di messaggio?

L'elemento <ExposeHeaders> utilizza la seguente sintassi:

Sintassi

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

Esempio

This example specifies that the browsers are allowed to access all HTTP headers.

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

<GeneratePreflightResponse>

Indica se il criterio deve generare e restituire la risposta preflight CORS. Se false, non viene inviata alcuna risposta. Vengono invece compilate le seguenti variabili di flusso:

• 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

Valore predefinito	true
Obbligatorio?	Facoltativo
Tipo	Booleano
Elemento principale	<CORS>
Elementi secondari	Nessuno

L'elemento <GeneratePreflightResponse> utilizza la seguente sintassi:

Sintassi

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

Esempio

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 l'elaborazione si interrompe quando viene rilevata una variabile non risolta. Imposta true per ignorare le variabili non risolte e continuare l'elaborazione; altrimenti false.

Valore predefinito	true
Obbligatorio?	Facoltativo
Tipo	Booleano
Elemento principale	<CORS>
Elementi secondari	Nessuno

L'elemento <IgnoreUnresolvedVariables> utilizza la seguente sintassi:

Sintassi

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

Esempio

This example specifies that processing continues when an unresolved variable is encountered.

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

<MaxAge>

Specifica per quanto tempo i risultati di una richiesta preflight possono essere memorizzati nella cache in secondi. Un valore di -1 inserisce nell'intestazione Access-Control-Max-Age un valore di -1, che disabilita la memorizzazione nella cache, richiedendo un controllo preliminare OPTIONS per tutte le chiamate. Questa impostazione è definita nella specifica Access-Control-Max-Age.

Valore predefinito	1800
Obbligatorio?	Facoltativo
Tipo	Numero intero
Elemento principale	<CORS>
Elementi secondari	Nessuno

L'elemento <MaxAge> utilizza la seguente sintassi:

Sintassi

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

Esempio:
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>

Esempio:
No 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>

Note sull'utilizzo

Richieste OPTIONS

Quando una richiesta OPTIONS viene ricevuta ed elaborata dalle norme CORS, l'esecuzione del flusso proxy viene trasferita direttamente al pre-flusso della risposta proxy, saltando completamente i flussi di richiesta e continua l'esecuzione da lì. Non è necessario creare una condizione per ignorare la richiesta OPTIONS nel flusso di richieste proxy.

Nelle chiamate successive, quando viene eseguito il criterio CORS, se il MaxAge impostato nel criterio non è scaduto, il flusso continua normalmente. Durante il flusso di risposta finale, appena prima di "Response Sent to Client", un passaggio di esecuzione CORS speciale "CORSResponseOrErrorFlowExecution" imposta le intestazioni della risposta CORS (Access-Control-Allow-Credentials, Access-Control-Allow-Origin e Access-Control-Expose-Headers) per restituire una risposta con convalida CORS.

Codici di errore

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>

Variabili di flusso

Verrà aggiunto un oggetto CorsFlowInfo FlowInfo e sarà disponibile per il tracciamento.

Proprietà	Tipo	Lettura/scrittura	Descrizione	Inizio ambito
cross_origin_resource_sharing.allow.credentials	Booleano	Lettura/scrittura	Valore ottenuto da <AllowCredentials>	Richiesta proxy
cross_origin_resource_sharing.allow.headers	Stringa	Lettura/scrittura	Valore ottenuto da <AllowHeaders>	Richiesta proxy
cross_origin_resource_sharing.allow.methods	Stringa	Lettura/scrittura	Valore ottenuto da <AllowMethods>	Richiesta proxy
cross_origin_resource_sharing.allow.origin	Stringa	Lettura/scrittura	L'origine della richiesta consentita, vuota se non è presente nella lista consentita	Richiesta proxy
cross_origin_resource_sharing.allow.origins.list	Stringa	Lettura/scrittura	Valore ottenuto da <AllowOrigins>	Richiesta proxy
cross_origin_resource_sharing.expose.headers	Stringa	Lettura/scrittura	Valore ottenuto da <ExposeHeaders>	Richiesta proxy
cross_origin_resource_sharing.max.age	Numero intero	Lettura/scrittura	Valore ottenuto da <MaxAge>	Richiesta proxy
cross_origin_resource_sharing.preflight.accepted	Booleano	Lettura/scrittura	Indica se la richiesta preflight è accettata	Richiesta proxy
cross_origin_resource_sharing.request.headers	Stringa	Lettura/scrittura	Il valore dell'intestazione della richiesta Access-Control-Request-Headers	Richiesta proxy
cross_origin_resource_sharing.request.method	Stringa	Lettura/scrittura	Il valore dell'intestazione della richiesta Access-Control-Request-Method	Richiesta proxy
cross_origin_resource_sharing.request.origin	Stringa	Lettura/scrittura	Uguale a request.header.origin	Richiesta proxy
cross_origin_resource_sharing.request.type	Stringa	Lettura/scrittura	Tipo di richiesta CORS. Valori possibili: REALE:una richiesta che non è una richiesta di preflight PRE_FLIGHT::una richiesta preflight	Richiesta proxy