Partage des ressources entre origines multiples (CORS)

Configuration Exemples de configuration

Le règlement d'origine identique est un règlement de sécurité appliqué aux applications Web côté client (telles que les navigateurs Web) afin d'empêcher les interactions entre des ressources d'origines différentes. Bien que cette mesure de sécurité soit utile pour éviter les comportements malveillants, elle empêche également les interactions légitimes entre des origines connues. Par exemple, un script sur une page hébergée sur example.appspot.com peut avoir besoin d'utiliser des ressources stockées dans un bucket Cloud Storage à l'adresse example.storage.googleapis.com. Toutefois, comme il s'agit de deux origines différentes du point de vue du navigateur, celui-ci n'autorisera pas un script provenant de example.appspot.com à extraire des ressources de example.storage.googleapis.com.

Pour contourner cette limitation, le World Wide Web Consortium (W3C) a mis au point la spécification de partage des ressources entre origines multiples (CORS, Cross-Origin Resource Sharing). Cloud Storage est compatible avec cette spécification et vous permet de configurer vos buckets de sorte qu'ils l'acceptent. En reprenant l'exemple ci-dessus, vous pouvez configurer le bucket example.storage.googleapis.com afin qu'un navigateur puisse partager ses ressources avec des scripts provenant de example.appspot.com.

Pour plus d'informations sur les composants de la configuration CORS, consultez la page Définir la configuration CORS d'un bucket.

Fonctionnement du CORS

Il existe deux types de requêtes CORS, les simples et les pré-vérifiées. Une requête simple peut être lancée directement. Une requête pré-vérifiée doit envoyer au serveur une requête de "vérification préliminaire" afin d'obtenir une autorisation avant de poursuivre la requête principale. Une requête est pré-vérifiée si l'une des conditions suivantes est vraie :

  • Elle utilise des méthodes autres que GET, HEAD ou POST.
  • Elle utilise la méthode POST avec un paramètre Content-Type différent de text/plain, application/x-www-form-urlencoded ou multipart/form-data.
  • Elle définit des en-têtes personnalisés. Par exemple, X-PINGOTHER.

Le processus suivant se produit lorsqu'un navigateur envoie une requête simple à Cloud Storage :

  1. Le navigateur ajoute l'en-tête Origin à la requête. L'en-tête Origin contient l'origine de la ressource qui cherche à partager les ressources du bucket Cloud Storage, par exemple Origin:https://www.example.appspot.com.

  2. Cloud Storage compare la méthode HTTP de la requête et la valeur de l'en-tête Origin aux informations sur les méthodes et les origines de la configuration CORS du bucket cible, afin de déterminer s'il existe des correspondances. Le cas échéant, Cloud Storage inclut l'en-tête Access-Control-Allow-Origin dans sa réponse. L'en-tête Access-Control-Allow-Origin contient la valeur de l'en-tête Origin de la requête initiale.

  3. Le navigateur reçoit la réponse et vérifie si la valeur Access-Control-Allow-Origin correspond au domaine spécifié dans la requête d'origine. Si c'est le cas, la requête aboutit. Si la valeur ne correspond pas, ou si l'en-tête Access-Control-Allow-Origin n'est pas présent dans la réponse, la requête échoue.

Une requête pré-vérifiée accomplit d'abord les étapes ci-après. Si celles-ci se déroulent correctement, elle suit alors le même processus qu'une requête simple :

  1. Le navigateur envoie une requête OPTIONS contenant les éléments Requested Method et Requested Headers de la requête principale.

  2. Cloud Storage répond avec les valeurs des en-têtes et des méthodes HTTP autorisés par la ressource ciblée. Si l'une des valeurs de méthode ou d'en-tête de la requête de pré-vérification ne fait pas partie de l'ensemble de méthodes et d'en-têtes autorisés par la ressource ciblée, la requête échoue. La requête principale n'est alors pas envoyée.

Voici une description simplifiée du CORS. Pour obtenir une description plus complète, consultez la spécification Fetch.

Compatibilité du CORS avec Cloud Storage

Cloud Storage vous permet de définir la configuration CORS au niveau du bucket seulement. Vous pouvez définir la configuration CORS d'un bucket à l'aide de divers outils. Cependant, différents points de terminaison Cloud Storage traitent les requêtes CORS différemment :

  • Les points de terminaison de l'API JSON autorisent toujours les requêtes CORS et renvoient des valeurs par défaut dans les en-têtes de réponse CORS, quelle que soit la configuration définie sur le bucket.

  • Les points de terminaison de l'API XML n'acceptent que les requêtes CORS basées sur la configuration du bucket et renvoient des valeurs d'en-tête CORS spécifiques en réponse à cette configuration.

  • Le point de terminaison de téléchargement du navigateur authentifié storage.cloud.google.com n'autorise pas les requêtes CORS. Notez que la console Google Cloud fournit ce point de terminaison pour le lien d'URL public de chaque objet.

Vous pouvez obtenir une réponse de Cloud Storage contenant les en-têtes CORS à l'aide de l'une des URL de requête de l'API XML suivantes :

storage.googleapis.com/BUCKET_NAME
BUCKET_NAME.storage.googleapis.com

Pour plus d'informations sur les URL de requête de l'API XML, consultez la page Points de terminaison de requêtes.

Composants d'une configuration CORS

Lorsque vous utilisez l'API XML, les valeurs que vous définissez dans la configuration CORS de votre bucket déterminent les en-têtes CORS renvoyés par Cloud Storage dans une réponse HTTP. Lorsque vous utilisez l'API JSON, Cloud Storage n'évalue pas la configuration de votre bucket et renvoie à la place des valeurs d'en-tête par défaut.

Le tableau suivant décrit les champs d'une configuration CORS et le comportement de réponse des API XML et JSON. Pour en savoir plus sur l'utilisation de ces champs, consultez les Exemples de configuration CORS.

Champ1 Description Comportement de réponse de l'API XML Comportement de réponse de l'API JSON
origin Spécifiez les origines que vous souhaitez autoriser pour le Cross-Origin Resource Sharing avec ce bucket Cloud Storage. Par exemple, https://origin1.example.com. Si l'origine de la requête d'un navigateur correspond à l'une des origines de votre configuration CORS, Cloud Storage renvoie Access-Control-Allow-Origin au navigateur. En l'absence de correspondance, Cloud Storage n'inclut pas Access-Control-Allow-Origin dans la réponse. Vous pouvez alors fournir une valeur générique qui autorise l'accès à toutes les origines : <Origin>*</Origin>. Cloud Storage renvoie l'en-tête Access-Control-Allow-Origin défini sur l'origine de la requête.
method

Spécifiez les méthodes HTTP que vous souhaitez autoriser pour le Cross-Origin Resource Sharing avec ce bucket Cloud Storage. La valeur est renvoyée dans l'en-tête Access-Control-Allow-Methods en réponse aux requêtes préalables qui ont abouti.

Étant donné que OPTIONS est une méthode standard utilisée par les navigateurs pour lancer des requêtes préalables, vous ne devez pas spécifier OPTIONS dans votre configuration CORS.

Cloud Storage accepte les méthodes suivantes : DELETE, GET, HEAD, POST et PUT.

Cloud Storage compare les méthodes envoyées par le navigateur dans l'en-tête Access-Control-Request-Methods à la configuration CORS du bucket. Si elles ne correspondent pas, Cloud Storage renvoie un code de réponse 200 sans en-têtes de réponse CORS.

 Cloud Storage renvoie l'en-tête Access-Control-Allow-Methods défini sur les méthodes suivantes : DELETE, GET, HEAD, PATCH, POST et PUT.
responseHeader Spécifiez les en-têtes que vous souhaitez autoriser pour le Cross-Origin Resource Sharing avec ce bucket Cloud Storage. La valeur est renvoyée dans l'en-tête Access-Control-Allow-Headers en réponse aux requêtes préalables qui ont abouti. Pour les requêtes préliminaires, Cloud Storage compare les en-têtes envoyés depuis le navigateur dans l'en-tête Access-Control-Request-Headers à la configuration CORS du bucket. S'ils ne correspondent pas, Cloud Storage ne renvoie pas les en-têtes de réponse CORS. Cloud Storage renvoie l'ensemble d'en-têtes Access-Control-Allow-Headers égal aux valeurs spécifiées par l'en-tête Access-Control-Request-Headers.
maxAgeSeconds (facultatif) Spécifiez le nombre de secondes pendant lesquelles le navigateur est autorisé à effectuer des requêtes avant de devoir répéter la requête préliminaire. On l'appelle également le délai d'expiration du cache. Cette valeur est renvoyée dans l'en-tête Access-Control-Max-Age dans les réponses aux requêtes préalables. Par exemple, 3600 définit le délai d'expiration du cache sur 1 heure. Cloud Storage renvoie l'en-tête Access-Control-Max-Age avec le délai d'expiration du cache spécifié. Si vous omettez de renseigner ce champ, Cloud Storage renvoie la valeur par défaut 3600. Cloud Storage renvoie l'en-tête Access-Control-Max-Age avec la valeur par défaut 3600.

1 Les noms indiqués dans la colonne "Champ" sont spécifiques à l'API JSON. Lorsque vous définissez une configuration CORS à l'aide de l'API XML, utilisez le format spécifique à XML.

Spécifier plusieurs origines, méthodes ou en-têtes

Pour savoir comment définir plusieurs origines, méthodes ou en-têtes dans une configuration CORS, consultez la liste suivante:

  • Lorsque vous utilisez l'API JSON, vous pouvez spécifier plusieurs origines, méthodes ou en-têtes à l'aide d'un tableau d'éléments séparés par une virgule. Par exemple, "method": ["GET", "PUT"].

  • Lorsque vous utilisez l'API XML, vous pouvez spécifier plusieurs origines, méthodes ou en-têtes à l'aide d'éléments distincts. Par exemple :

    <Methods>
  <Method>PUT</Method>
  <Method>GET</Method>
</Methods>

  • Pour autoriser les requêtes depuis n'importe quelle origine, définissez l'origine sur *. Par exemple, "origin": ["*"] dans l'API JSON ou <Origin>*</Origin> dans l'API XML. Bien que cette origine soit utile pour tester les configurations, dans la plupart des cas, vous souhaiterez limiter les origines des requêtes afin d'empêcher toute utilisation indésirable de vos ressources.

Autres considérations

Le tableau suivant décrit les éléments à prendre en compte lorsque vous effectuez des requêtes à l'aide d'identifiants ou d'en-têtes de contrôle des accès :

Propriété ou en-tête Description Comportement de réponse de l'API XML Comportement de réponse de l'API JSON
Identifiants Cookies, en-têtes d'autorisation ou certificats client TLS. Cloud Storage ne renvoie jamais l'en-tête Access-Control-Allow-Credentials. Les identifiants CORS ne sont pas compatibles avec l'API XML.

Pour les requêtes simples, si la requête CORS est approuvée, l'en-tête Access-Control-Allow-Credentials est défini sur "true".

Pour les requêtes préalables, si Access-Control-Request-Method est vide, Cloud Storage définit Access-Control-Allow-Credentials sur "true" et rejette la requête avec 404 - Not Found.
En-têtes exposés Pour les requêtes préliminaires, l'en-tête de requête Access-Control-Request-Headers indique quels en-têtes peuvent être inclus dans une future requête CORS. L'en-tête de réponse Access-Control-Expose-Headers est inclus dans la réponse du serveur et indique au client quels en-têtes peuvent être exposés. Pour les requêtes simples, Access-Control-Expose-Headers répertorie les valeurs des en-têtes de réponse dans votre configuration CORS. Pour les requêtes simples, Access-Control-Expose-Headers renvoie les valeurs spécifiées dans Access-Control-Request-Headers si elles font partie d'une liste d'en-têtes HTTP courants.

Autoriser les buckets à accéder aux ressources externes

Vous devrez peut-être parfois autoriser des scripts hébergés dans Cloud Storage à accéder à des ressources statiques hébergées sur un site Web externe à Cloud Storage. Dans ce scénario, le site Web diffuse les en-têtes CORS afin que l'accès au contenu se trouvant sur storage.googleapis.com soit autorisé.

Nous vous recommandons de dédier un bucket spécifique à cet accès aux données. Cette approche empêche votre site de surexposer par inadvertance des ressources statiques à l'intégralité de storage.googleapis.com. Par exemple, si vous souhaitez dédier un bucket nommé mybucket à l'accès aux données, vous devez faire en sorte que le site Web diffuse l'en-tête CORS Access-Control-Allow-Origin: https://mybucket.storage.googleapis.com au lieu de Access-Control-Allow-Origin: https://storage.googleapis.com.

Compatibilité du CORS côté client

La plupart des navigateurs effectuent une requête interdomaine au moyen de l'objet XMLHttpRequest. XMLHttpRequest s'occupe intégralement de l'insertion des en-têtes appropriés et de la gestion de l'interaction CORS avec le serveur. Vous n'avez pas besoin d'ajouter de nouveau code pour bénéficier de la compatibilité du CORS sur les buckets Cloud Storage.

Étape suivante