Uso compartido de recursos entre dominios (CORS)

Configuración Ejemplos de configuración

El uso compartido de recursos entre dominios (CORS) permite que las aplicaciones web del lado del cliente accedan a recursos de diferentes orígenes. Cloud Storage admite la especificación CORS, que te permite configurar tus segmentos para compartir recursos de forma segura con secuencias de comandos de otros orígenes. Por ejemplo, puedes usar CORS para permitir que tu aplicación web https://example-app.appspot.com acceda a un recurso del origen https://example-data.storage.googleapis.com.

Para obtener más información sobre los componentes de configuración de CORS, consulta Set Bucket CORS (Definir CORS de un segmento).

Cómo funciona CORS

Usa CORS cuando quieras que tu sitio web obtenga archivos, imágenes o secuencias de comandos directamente de un segmento de Cloud Storage mediante una solicitud basada en navegador.

Permitir el acceso entre dominios

De forma predeterminada, los navegadores web aplican una medida de seguridad llamada política del mismo origen. La política del mismo origen impide que una secuencia de comandos de un sitio web interactúe con recursos de otro dominio. Aunque esto protege a los usuarios de los sitios maliciosos, también bloquea las solicitudes legítimas. Por ejemplo, si tu aplicación web https://example-app.appspot.com intenta acceder a un recurso en el origen https://example-data.storage.googleapis.com, el navegador bloqueará la solicitud de forma predeterminada porque los dominios no coinciden.

La especificación de CORS ofrece a los servidores una forma de indicar al navegador: "Confío en este dominio concreto, así que permite la solicitud".

Cloud Storage te permite definir una configuración de CORS en tu segmento. Cuando se configura, Cloud Storage envía encabezados HTTP específicos al navegador (como Access-Control-Allow-Origin) que autorizan al navegador a compartir los recursos del segmento con tu aplicación web.

Tipos de solicitudes

Las solicitudes CORS funcionan de dos formas: simples y preparatorias. Una solicitud simple se procesa directamente, mientras que una solicitud preparatoria primero envía una solicitud preliminar para obtener permiso.

Solicitudes sencillas

Cuando un navegador hace una solicitud simple a Cloud Storage, se produce el siguiente proceso:

El navegador añade el encabezado Origin a la solicitud. El encabezado Origin contiene el origen del recurso que quiere compartir los recursos del segmento de Cloud Storage. Por ejemplo, Origin:https://www.example-app.appspot.com.
Cloud Storage compara el método HTTP de la solicitud y el valor del encabezado Origin con la información de Methods y Origins de la configuración CORS del cubo de destino para ver si hay coincidencias. Si hay, Cloud Storage incluye el encabezado Access-Control-Allow-Origin en su respuesta. El encabezado Access-Control-Allow-Origin contiene el valor del encabezado Origin de la solicitud inicial.
El navegador recibe la respuesta y comprueba si el valor de Access-Control-Allow-Origin coincide con el dominio especificado en la solicitud original. Si coinciden, la solicitud se realiza correctamente. Si no coinciden o si el encabezado Access-Control-Allow-Origin no está presente en la respuesta, la solicitud falla.

Solicitudes preflight

Una solicitud se envía previamente si se da alguna de las siguientes circunstancias:

Utiliza métodos distintos a GET, HEAD o POST.
Usa el método POST con un Content-Type que no sea text/plain, application/x-www-form-urlencoded ni multipart/form-data.
Define encabezados personalizados. Por ejemplo, X-PINGOTHER.

Una solicitud preflighted realiza primero los siguientes pasos. Si se realiza correctamente, sigue el mismo proceso que una solicitud sencilla:

El navegador envía una solicitud OPTIONS que contiene el Requested Method y el Requested Headers de la solicitud principal.
Cloud Storage responde con los valores de los métodos HTTP y los encabezados permitidos por el recurso de destino. Si alguno de los valores de método o de encabezado de la solicitud de verificación previa no se encuentra en el conjunto de métodos y encabezados permitidos por el recurso de destino, la solicitud fallará y no se enviará la solicitud principal.

Para obtener una descripción más completa de las solicitudes CORS, consulta la especificación Fetch.

Compatibilidad con CORS de Cloud Storage

Cloud Storage te permite definir configuraciones de CORS a nivel de segmento. Los endpoints de la API JSON y la API XML gestionan las solicitudes CORS y devuelven los encabezados de respuesta de forma diferente. Conocer estos comportamientos te ayudará a configurar tus contenedores de forma eficaz:

Los endpoints de la API JSON siempre permiten solicitudes CORS y devuelven valores predeterminados en los encabezados de respuesta CORS, independientemente de la configuración definida en el segmento.
Los endpoints de la API XML solo permiten solicitudes CORS basadas en la configuración del cubo y devuelven valores de encabezado CORS específicos en respuesta a esa configuración.
El endpoint de descarga del navegador autenticado storage.cloud.google.com no permite solicitudes CORS. Ten en cuenta que la consola Google Cloud proporciona este endpoint para el enlace de URL pública de cada objeto.

Puede usar cualquiera de las siguientes URLs de solicitud de la API XML para obtener una respuesta de Cloud Storage que contenga los encabezados CORS:

storage.googleapis.com/BUCKET_NAME

BUCKET_NAME.storage.googleapis.com

Para obtener información sobre las URLs de solicitud de la API XML, consulta Endpoints de solicitud.

Componentes de una configuración de CORS

Cuando se usa la API XML, los valores que se definen en la configuración de CORS del cubo determinan los encabezados CORS que Cloud Storage devuelve en una respuesta HTTP. Cuando se usa la API JSON, Cloud Storage no evalúa la configuración de tu contenedor y, en su lugar, devuelve los valores predeterminados de los encabezados.

En la siguiente tabla se describen los campos de una configuración de CORS y el comportamiento de respuesta de las APIs XML y JSON. Para saber cómo se usan estos campos, consulta los ejemplos de configuración de CORS.

Campo ¹	Descripción	Comportamiento de las respuestas de la API XML	Comportamiento de la respuesta de la API JSON
`origin`	Especifica los orígenes que quieras permitir para compartir recursos entre orígenes con este segmento de Cloud Storage. Por ejemplo, `https://origin1.example.com`.	Si el origen de la solicitud de un navegador coincide con un origen de tu configuración de CORS, Cloud Storage devuelve `Access-Control-Allow-Origin` al navegador. Si no hay ninguna coincidencia, Cloud Storage no incluye `Access-Control-Allow-Origin` en la respuesta. Puedes proporcionar un valor comodín que conceda acceso a todos los orígenes: `<Origin>*</Origin>`.	Cloud Storage devuelve el encabezado `Access-Control-Allow-Origin` definido en el origen de la solicitud.
`method`	Especifica los métodos HTTP que quieras permitir para el uso compartido de recursos entre orígenes con este segmento de Cloud Storage. El valor se devuelve en el encabezado `Access-Control-Allow-Methods` en respuesta a solicitudes de comprobación previa correctas. Como `OPTIONS` es un método estándar que usan los navegadores para iniciar solicitudes preparatorias, no debes especificar `OPTIONS` en tu configuración de CORS.	Cloud Storage admite los siguientes métodos: `DELETE`, `GET`, `HEAD`, `POST`, `PUT`. Cloud Storage comprueba los métodos enviados desde el navegador en el encabezado `Access-Control-Request-Methods` con la configuración CORS del segmento. Si no hay ninguna coincidencia, Cloud Storage devuelve un código de respuesta `200` sin encabezados de respuesta CORS.	Cloud Storage devuelve el encabezado `Access-Control-Allow-Methods` definido en los siguientes métodos: `DELETE`, `GET`, `HEAD`, `PATCH`, `POST`, `PUT`.
`responseHeader`	Especifica qué encabezados quieres permitir para compartir recursos entre orígenes con este segmento de Cloud Storage. El valor se devuelve en el encabezado `Access-Control-Allow-Headers` en respuesta a las solicitudes de comprobación preliminar correctas.	En el caso de las solicitudes preparatorias, Cloud Storage comprueba los encabezados enviados desde el navegador en el encabezado `Access-Control-Request-Headers` con la configuración CORS del cubo. Si no hay ninguna coincidencia, Cloud Storage no devuelve encabezados de respuesta CORS.	Cloud Storage devuelve el encabezado `Access-Control-Allow-Headers` con los valores especificados en el encabezado `Access-Control-Request-Headers`.
`maxAgeSeconds` (opcional)	Especifica el número de segundos que el navegador puede hacer solicitudes antes de que deba repetir la solicitud de comprobación previa. También se conoce como tiempo de vencimiento de la caché. Este valor se devuelve en el encabezado `Access-Control-Max-Age` de las respuestas a las solicitudes de comprobación previa. Por ejemplo, `3600` define el tiempo de caducidad de la caché en 1 hora.	Cloud Storage devuelve el encabezado `Access-Control-Max-Age` con el tiempo de caducidad de la caché especificado. Si omites este campo, Cloud Storage devolverá el valor predeterminado `3600`.	Cloud Storage devuelve el encabezado `Access-Control-Max-Age` con el valor predeterminado `3600`.

¹ Los nombres documentados en la columna Campo son específicos de la API JSON. Cuando utilice la API XML para definir una configuración de CORS, use el formato específico de XML.

Especificar varios orígenes, métodos o encabezados

Para saber cómo definir varios orígenes, métodos o encabezados en una configuración de CORS, consulta la siguiente lista:

Cuando se usa la API JSON, se pueden especificar varios orígenes, métodos o encabezados mediante una matriz separada por comas. Por ejemplo, "method": ["GET", "PUT"].

Precaución: Cuando configuras el CORS mediante la API JSON, se aceptan las solicitudes de todos los orígenes, independientemente del valor del campo origin en la configuración del CORS.
Cuando se usa la API XML, se pueden especificar varios orígenes, métodos o encabezados mediante elementos independientes. Por ejemplo:
```
<Methods>
  <Method>PUT</Method>
  <Method>GET</Method>
</Methods>
```
Para permitir que se hagan solicitudes desde cualquier origen, define el origen como el comodín *. Por ejemplo, "origin": ["*"] en la API JSON o <Origin>*</Origin> en la API XML. Aunque este origen es útil para probar configuraciones, en la mayoría de los casos, le recomendamos que restrinja los orígenes de las solicitudes para evitar un uso no deseado de sus recursos.

Consideraciones adicionales

En la siguiente tabla se describen las consideraciones que debes tener en cuenta al hacer solicitudes con encabezados de credenciales o de control de acceso:

Propiedad o encabezado Descripción Comportamiento de las respuestas de la API XML Comportamiento de la respuesta de la API JSON

Credenciales

Cookies, encabezados de autorización o certificados de cliente TLS.

Propiedad o encabezado	Descripción	Comportamiento de las respuestas de la API XML	Comportamiento de la respuesta de la API JSON
Credenciales	Cookies, encabezados de autorización o certificados de cliente TLS.	Cloud Storage nunca devuelve el encabezado `Access-Control-Allow-Credentials`. La API XML no admite las credenciales CORS.	En las solicitudes simples, si se aprueba la solicitud CORS, el encabezado `Access-Control-Allow-Credentials` se establece en true. En el caso de las solicitudes de comprobación previa, si `Access-Control-Request-Method` está vacío, Cloud Storage asigna el valor true a `Access-Control-Allow-Credentials` y rechaza la solicitud con `404 - Not Found`.
Encabezados expuestos	En las solicitudes preparatorias, el encabezado de solicitud `Access-Control-Request-Headers` indica qué encabezados puede incluir una futura solicitud CORS. La cabecera de respuesta `Access-Control-Expose-Headers` se incluye en la respuesta del servidor e indica al cliente qué cabeceras se pueden exponer.	En el caso de las solicitudes simples, `Access-Control-Expose-Headers` muestra los valores de los encabezados de respuesta en tu configuración de CORS.	En el caso de las solicitudes sencillas, `Access-Control-Expose-Headers` devuelve los valores especificados en `Access-Control-Request-Headers` si forman parte de una lista de encabezados HTTP comunes.

Cloud Storage nunca devuelve el encabezado Access-Control-Allow-Credentials. La API XML no admite las credenciales CORS.

En las solicitudes simples, si se aprueba la solicitud CORS, el encabezado Access-Control-Allow-Credentials se establece en true.

En el caso de las solicitudes de comprobación previa, si Access-Control-Request-Method está vacío, Cloud Storage asigna el valor true a Access-Control-Allow-Credentials y rechaza la solicitud con 404 - Not Found.

Encabezados expuestos En las solicitudes preparatorias, el encabezado de solicitud Access-Control-Request-Headers indica qué encabezados puede incluir una futura solicitud CORS. La cabecera de respuesta Access-Control-Expose-Headers se incluye en la respuesta del servidor e indica al cliente qué cabeceras se pueden exponer. En el caso de las solicitudes simples, Access-Control-Expose-Headers muestra los valores de los encabezados de respuesta en tu configuración de CORS. En el caso de las solicitudes sencillas, Access-Control-Expose-Headers devuelve los valores especificados en Access-Control-Request-Headers si forman parte de una lista de encabezados HTTP comunes.

Permitir que los contenedores accedan a recursos externos

En ocasiones, puede que quieras permitir que las secuencias de comandos alojadas en Cloud Storage accedan a recursos estáticos alojados en un sitio web externo a Cloud Storage. En este caso, el sitio web envía encabezados CORS para que se permita el acceso al contenido de storage.googleapis.com.

Como práctica recomendada, debes dedicar un contenedor específico a este acceso a los datos. De esta forma, se evita que tu sitio exponga en exceso recursos estáticos a todos los usuarios de storage.googleapis.com por error. Por ejemplo, si quieres dedicar un contenedor llamado mybucket al acceso a los datos, el sitio web debe servir el encabezado CORS Access-Control-Allow-Origin: https://mybucket.storage.googleapis.com en lugar de Access-Control-Allow-Origin: https://storage.googleapis.com.

Compatibilidad con CORS del lado del cliente

La mayoría de los navegadores usan el objeto XMLHttpRequest para hacer una solicitud entre dominios. XMLHttpRequest se encarga de insertar los encabezados correctos y de gestionar la interacción CORS con el servidor. No tienes que añadir ningún código nuevo para aprovechar la compatibilidad con CORS en los contenedores de Cloud Storage.

Siguientes pasos

Consulte cómo habilitar CORS en su segmento.
Consulta ejemplos de configuración de CORS, incluido un ejemplo que elimina la configuración de CORS de un segmento.
Consulta cómo solucionar problemas con las solicitudes CORS.