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
ouPOST
. - Elle utilise la méthode
POST
avec un paramètreContent-Type
différent detext/plain
,application/x-www-form-urlencoded
oumultipart/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 :
Le navigateur ajoute l'en-tête
Origin
à la requête. L'en-têteOrigin
contient l'origine de la ressource qui cherche à partager les ressources du bucket Cloud Storage, par exempleOrigin:https://www.example.appspot.com
.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êteAccess-Control-Allow-Origin
dans sa réponse. L'en-têteAccess-Control-Allow-Origin
contient la valeur de l'en-têteOrigin
de la requête initiale.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êteAccess-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 :
Le navigateur envoie une requête
OPTIONS
contenant les élémentsRequested Method
etRequested Headers
de la requête principale.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 Étant donné que |
Cloud Storage accepte les méthodes suivantes : Cloud Storage compare les méthodes envoyées par le navigateur dans l'en-tête |
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 Pour les requêtes préalables, si |
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
- Découvrez comment activer CORS pour votre bucket.
- Découvrez des exemples de configuration CORS, y compris un exemple qui supprime la configuration CORS d'un bucket.