Règle CORS

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d' Apigee Edge.

Le partage de ressources entre origines (CORS) est un mécanisme standard qui permet aux appels XMLHttpRequest (XHR) exécutés sur une page Web d'interagir avec des ressources extérieures au domaine d'origine. CORS est une solution couramment mise en œuvre à la règle de même origine appliquée par tous les navigateurs.

Par exemple, si vous effectuez un appel XHR à l'API Twitter à partir de code JavaScript exécuté dans votre navigateur, l'appel échoue. En effet, le domaine qui diffuse la page vers votre navigateur est différent du domaine diffusant l'API Twitter. CORS offre une solution à ce problème en autorisant des serveurs à accepter explicitement le partage de ressources entre origines multiples.

La fonctionnalité Essayer cette API incluse dans la documentation sur le portail des développeurs est un cas d'utilisation du CORS. Pour en savoir plus, consultez Configurer votre proxy d'API pour qu'il soit compatible avec le panneau "Essayer cette API".

La règle CORS permet aux clients Apigee de définir des règles CORS pour les API utilisées par les applications Web.

Cette règle est une règle standard qui peut être déployée sur n'importe quel type d'environnement. Pour en savoir plus sur les types de règles et la disponibilité avec chaque type d'environnement, consultez la section Types de règles.

Élément <CORS>

Définit la règle CORS.

Valeur par défaut Consultez l'onglet Règles par défaut ci-dessous.
Obligatoire ? Obligatoire
Type Objet complexe
Élément parent ND
Éléments enfants <AllowCredentials>
<AllowHeaders>
<AllowMethods>
<AllowOrigins>
<DisplayName>
<ExposeHeaders>
<GeneratePreflightResponse>
<IgnoreUnresolvedVariables>
<MaxAge>

L'élément <CORS> utilise la syntaxe suivante :

Syntaxe

L'élément <CORS> utilise la syntaxe suivante :


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

Stratégie par défaut

L'exemple suivant montre les paramètres par défaut lorsque vous ajoutez la règle CORS à votre flux dans l'interface utilisateur 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>

Lorsque vous insérez une nouvelle règle CORS dans l'interface utilisateur d'Apigee, le modèle contient des bouchons pour toutes les opérations possibles. En règle générale, vous devez sélectionner les opérations que vous souhaitez effectuer avec cette règle et supprimer le reste des éléments enfants. Par exemple, si vous souhaitez spécifier les méthodes HTTP autorisées à accéder à la ressource, utilisez l'élément <AllowMethods> et supprimez les autres éléments enfants de la règle pour la rendre plus lisible.

Cet élément possède les attributs suivants qui sont communs à toutes les règles :

Attribut Par défaut Obligatoire ? Description
name ND Obligatoire

Nom interne de la règle. La valeur de l'attribut name peut contenir des lettres, des chiffres, des espaces, des tirets, des traits de soulignement et des points. Cette valeur ne peut pas dépasser 255 caractères.

Vous pouvez également utiliser l'élément <DisplayName> pour ajouter un libellé à la règle dans l'éditeur de proxy de l'interface utilisateur de gestion avec un nom différent, en langage naturel.
continueOnError faux Facultatif Définissez sur false pour afficher une erreur en cas d'échec d'une règle. Il s'agit du comportement attendu pour la plupart des règles. Définissez sur true pour que l'exécution du flux se poursuive même après l'échec d'une règle. Voir aussi :
enabled true Facultatif Définissez sur true pour appliquer la règle. Définissez sur false pour désactiver la règle. La règle ne sera pas appliquée même si elle reste associée à un flux.
async   faux Obsolète Cet attribut est obsolète.

Chacun des éléments enfants est décrit dans les sections ci-après.

Exemples

Des exemples sont fournis pour tous les éléments enfants des sections suivantes.

Référence d'élément enfant

Cette section décrit les éléments enfants de <CORS>.

<AllowCredentials>

Indique si l'appelant est autorisé à envoyer la requête réelle (et non la version préliminaire) à l'aide d'identifiants. Se traduit en un en-tête Access-Control-Allow-Credentials.

Valeur par défaut Si aucune valeur n'est spécifiée, Access-Control-Allow-Credentials n'est pas défini.
Obligatoire ? Facultatif
Type Booléen
Élément parent <CORS>
Éléments enfants Aucun

L'élément <AllowCredentials> utilise la syntaxe suivante :

Syntaxe

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

Exemple

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>

Liste des en-têtes HTTP pouvant être utilisés pour demander la ressource. Sérialisée dans l'en-tête Access-Control-Allow-Headers.

Valeur par défaut Origin, Accept, X-Requested-With, Content-Type, Access-Control-Request-Method, Access-Control-Request-Headers
Obligatoire ? Facultatif
Type Chaîne, compatible avec les modèles de message*
Élément parent <CORS>
Éléments enfants Aucun

*Pour en savoir plus, consultez la page Qu'est-ce qu'un modèle de message ?

L'élément <AllowHeaders> utilise la syntaxe suivante :

Syntaxe

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

Exemple

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>

Liste des méthodes HTTP autorisées à accéder à la ressource. Le contenu est sérialisé dans l'en-tête Access-Control-Allow-Methods.

Valeur par défaut GET, POST, HEAD, OPTIONS
Obligatoire ? Facultatif
Type Chaîne, compatible avec les modèles de message*
Élément parent <CORS>
Éléments enfants Aucun

*Pour en savoir plus, consultez la page Qu'est-ce qu'un modèle de message ?

L'élément <AllowMethods> utilise la syntaxe suivante :

Syntaxe

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

Exemple :
Liste

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>

Exemple :
Caractère générique

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>

Liste des origines autorisées à accéder à la ressource. Utilisez un astérisque (*) pour autoriser l'accès à une ressource depuis n'importe quelle origine. Sinon, fournissez une liste d'autorisation contenant des origines séparées par des virgules. En cas de correspondance, la valeur Access-Control-Allow-Origin sortante est définie sur l'origine fournie par le client.

Valeur par défaut N/A
Obligatoire ? Obligatoire
Type Chaîne, compatible avec les modèles de message*
Élément parent <CORS>
Éléments enfants Aucun

*Pour en savoir plus, consultez la page Qu'est-ce qu'un modèle de message ?

L'élément <AllowOrigins> utilise la syntaxe suivante :

Syntaxe

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

Exemple :
URL unique

This example specifies a single URL origin that is allowed to access the resource. 

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

Exemple :
URL multiples

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>

Exemple :
Variable de contexte

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>

Exemple :
Variable de flux

Cet exemple spécifie une variable de flux représentant une origine autorisée à accéder à la ressource. 

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

Exemple :
Caractère générique

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

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

<DisplayName>

Utilisez-le, en plus de l'attribut name, pour appliquer un libellé à la règle dans l'éditeur de proxys de l'interface de gestion en utilisant un nom différent et plus naturel.

L'élément <DisplayName> est commun à toutes les règles.

Valeur par défaut N/A
Obligatoire ? Facultatif. Si vous omettez <DisplayName>, la valeur de l'attribut name de la règle est utilisée.
Type Chaîne
Élément parent <PolicyElement>
Éléments enfants Aucun

L'élément <DisplayName> utilise la syntaxe suivante :

Syntaxe

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

Exemple

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

L'élément <DisplayName> ne comporte aucun attribut ni élément enfant.

<ExposeHeaders>

Liste des en-têtes HTTP auxquels les navigateurs sont autorisés à accéder ou astérisque (*) pour autoriser tous les en-têtes HTTP. Sérialisé dans l'en-tête Access-Control-Expose-Headers.

Valeur par défaut Si aucune valeur n'est spécifiée, Access-Control-Expose-Headers n'est pas défini. Pas défaut, les en-têtes non simples ne sont pas exposés.
Obligatoire ? Facultatif
Type Chaîne, compatible avec les modèles de message*
Élément parent <CORS>
Éléments enfants Aucun

*Pour en savoir plus, consultez la page Qu'est-ce qu'un modèle de message ?

L'élément <ExposeHeaders> utilise la syntaxe suivante :

Syntaxe

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

Exemple

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>

Indiquez si la stratégie doit générer puis renvoyer la réponse CORS préliminaire. Si la valeur est false, aucune réponse n'est envoyée. Au lieu de cela, les variables de flux suivantes sont renseignées :

  • 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
Valeur par défaut true
Obligatoire ? Facultatif
Type Booléen
Élément parent <CORS>
Éléments enfants Aucun

L'élément <GeneratePreflightResponse> utilise la syntaxe suivante :

Syntaxe

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

Exemple

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>

Détermine si le traitement s'arrête lorsqu'une variable non résolue est rencontrée. Définissez la valeur sur true pour ignorer les variables non résolues et poursuivre le traitement, sinon false.

Valeur par défaut true
Obligatoire ? Facultatif
Type Booléen
Élément parent <CORS>
Éléments enfants Aucun

L'élément <IgnoreUnresolvedVariables> utilise la syntaxe suivante :

Syntaxe

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

Exemple

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>

Permet de spécifier la durée (en secondes) de mise en cache des résultats d'une requête préliminaire. Une valeur -1 renseigne l'en-tête Access-Control-Max-Age avec une valeur de -1, ce qui désactive la mise en cache et nécessite une vérification préliminaire des OPTIONS pour tous les appels. Ce paramètre est défini dans la spécification Access-Control-Max-Age.

Valeur par défaut 1800
Obligatoire ? Facultatif
Type Entier
Élément parent <CORS>
Éléments enfants Aucun

L'élément <MaxAge> utilise la syntaxe suivante :

Syntaxe

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

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

Exemple :
Aucun 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>

Remarques sur l'utilisation

Requêtes OPTIONS

Lorsqu'une requête OPTIONS est reçue et traitée par la règle CORS, l'exécution du flux du proxy est transférée directement vers le PreFlow de réponse du proxy, en ignorant entièrement les flux de requête et continue l'exécution à partir de là. Il n'est pas nécessaire de créer une condition pour ignorer la requête OPTIONS dans le flux de requête du proxy.

Lors des appels suivants, lorsque la stratégie CORS s'exécute, si le MaxAge défini dans la stratégie n'a pas expiré, le flux se poursuit normalement. Lors du flux de réponse final juste avant "Response Sent to Client", une étape d'exécution spéciale de CORS "CORSResponseOrErrorFlowExecution" définit les en-têtes de réponse CORS Access-Control-Allow-Credentials, Access-Control-Allow-Origin et Access-Control-Expose-Headers) pour renvoyer une réponse validée par CORS.

Codes d'erreur

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.

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

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

Variables de flux

Un objet CorsFlowInfo FlowInfo sera ajouté et pourra être suivi.

Propriété Type Lecture/Écriture Description Début du champ d'application
cross_origin_resource_sharing.allow.credentials Booléen Lecture/Écriture Valeur de <AllowCredentials> Requête de proxy
cross_origin_resource_sharing.allow.headers Chaîne Lecture/Écriture Valeur de <AllowHeaders> Requête de proxy
cross_origin_resource_sharing.allow.methods Chaîne Lecture/Écriture Valeur de <AllowMethods> Requête de proxy
cross_origin_resource_sharing.allow.origin Chaîne Lecture/Écriture L'origine de la requête qui est autorisée. Elle est vide si elle ne figure pas dans la liste d'autorisation. Requête de proxy
cross_origin_resource_sharing.allow.origins.list Chaîne Lecture/Écriture Valeur de <AllowOrigins> Requête de proxy
cross_origin_resource_sharing.expose.headers Chaîne Lecture/Écriture Valeur de <ExposeHeaders> Requête de proxy
cross_origin_resource_sharing.max.age Entier Lecture/Écriture Valeur de <MaxAge> Requête de proxy
cross_origin_resource_sharing.preflight.accepted Booléen Lecture/Écriture Indique si la requête de pré-vérification est acceptée Requête de proxy
cross_origin_resource_sharing.request.headers Chaîne Lecture/Écriture Valeur de l'en-tête de requête Access-Control-Request-Headers Requête de proxy
cross_origin_resource_sharing.request.method Chaîne Lecture/Écriture Valeur de l'en-tête de requête Access-Control-Request-Method Requête de proxy
cross_origin_resource_sharing.request.origin Chaîne Lecture/Écriture Même chose que pour request.header.origin Requête de proxy
cross_origin_resource_sharing.request.type Chaîne Lecture/Écriture

Type de requête CORS. Valeurs possibles :

  • ACTUAL : une requête qui n'est pas une requête de pré-vérification.
  • PRE_FLIGHT : une requête de pré-vérification.
 Requête de proxy