Uso compartido de recursos entre dominios (CORS)

Configuración Ejemplos de configuración

La política del mismo origen es una política de seguridad que se aplica a las aplicaciones web del lado del cliente (como los navegadores web) para evitar las interacciones entre recursos de orígenes diferentes. Aunque es útil para evitar comportamientos maliciosos, esta medida de seguridad también impide las interacciones legítimas entre orígenes conocidos. Por ejemplo, una secuencia de comandos de una página alojada en example.appspot.com puede necesitar usar recursos almacenados en un segmento de Cloud Storage en example.storage.googleapis.com. Sin embargo, como se trata de dos orígenes diferentes desde el punto de vista del navegador, este no permitirá que una secuencia de comandos de example.appspot.com obtenga recursos de example.storage.googleapis.com.

El uso compartido de recursos entre dominios (CORS) fue desarrollado por el Consorcio World Wide Web (W3C) para evitar esta limitación. Cloud Storage admite esta especificación, ya que te permite configurar tus segmentos para que admitan CORS. Siguiendo con el ejemplo anterior, puedes configurar el contenedor example.storage.googleapis.com para que un navegador pueda compartir sus recursos con las secuencias de comandos de example.appspot.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

Hay dos tipos de solicitudes CORS: simples y preparatorias. Se puede iniciar una solicitud sencilla directamente. Una solicitud preparatoria debe enviar una solicitud preliminar, "preparatoria", al servidor para obtener permiso antes de que se pueda procesar la solicitud principal. 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.

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

  1. 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.appspot.com.

  2. 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 de CORS del cubo de destino para ver si hay coincidencias. Si los 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.

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

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

  1. El navegador envía una solicitud OPTIONS que contiene el Requested Method y el Requested Headers de la solicitud principal.

  2. Cloud Storage responde con los valores de los métodos y encabezados HTTP 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.

Esta es una descripción simplificada de CORS. Para obtener una descripción más completa, consulta la especificación de Fetch.

Compatibilidad con CORS de Cloud Storage

Cloud Storage solo permite definir una configuración de CORS a nivel de segmento. Puede configurar el uso compartido de recursos entre orígenes en un segmento con varias herramientas. Sin embargo, los diferentes endpoints de Cloud Storage gestionan las solicitudes de CORS de diferentes formas:

  • 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 contenedor 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 bucket determinan los encabezados de 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 cubo y, en su lugar, devuelve valores de encabezado predeterminados.

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 1 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 compartir recursos entre orígenes con este segmento de Cloud Storage. El valor se devuelve en el encabezado Access-Control-Allow-Methods en respuesta a las 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 los encabezados que 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 omite este campo, Cloud Storage devuelve el valor predeterminado 3600. Cloud Storage devuelve el encabezado Access-Control-Max-Age con el valor predeterminado 3600.

1 Los nombres documentados en la columna Campo son específicos de la API JSON. Cuando uses la API XML para definir una configuración de CORS, utiliza 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"].

  • 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 *. 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 hay que tener en cuenta al hacer solicitudes con credenciales o encabezados 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. Cloud Storage nunca devuelve el encabezado Access-Control-Allow-Credentials. La API XML no admite las credenciales CORS.

En el caso de 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 de verificación previa, 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 sencillas, 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 sirve 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