Uso compartido de recursos multiorigen (CORS)

Configuración Muestras de configuración

El uso compartido de recursos multiorigen (CORS) permite que las aplicaciones web del cliente accedan a recursos de diferentes orígenes. Cloud Storage admite la especificación de CORS, lo que te permite configurar tus buckets 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 en el origen https://example-data.storage.googleapis.com.

Para obtener más información sobre los elementos de configuración de CORS, consulta la sección sobre la configuración de CORS de buckets.

Cómo funciona CORS

Usa CORS cuando quieras que tu sitio web recupere archivos, imágenes o secuencias de comandos directamente desde un bucket de Cloud Storage con una solicitud basada en el navegador.

Permite el acceso entre dominios

De forma predeterminada, los navegadores web aplican una medida de seguridad llamada política de mismo origen. La política de mismo origen impide que una secuencia de comandos de un sitio web interactúe con recursos de un dominio diferente. Si bien 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 proporciona una forma para que los servidores le digan al navegador: "Confío en este dominio específico, así que permite la solicitud".

Cloud Storage te permite establecer una configuración de CORS en tu bucket. 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 bucket con tu aplicación web.

Tipos de solicitud

Las solicitudes de CORS operan de dos maneras: simples y con verificación previa. Una solicitud simple se procesa directamente, mientras que una solicitud con verificación previa primero envía una solicitud preliminar para obtener permiso.

Solicitudes simples

El siguiente proceso ocurre cuando un navegador realiza una solicitud simple a Cloud Storage:

  1. El navegador agrega el encabezado Origin a la solicitud. El encabezado Origin contiene el origen del recurso que busca compartir los recursos del bucket de Cloud Storage, por ejemplo, Origin:https://www.example-app.appspot.com.

  2. Cloud Storage compara el método HTTP de la solicitud y el valor del encabezado Origin con la información de Métodos y Orígenes en la configuración de CORS del bucket de destino para ver si hay coincidencias. Si las 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 verifica si el valor de Access-Control-Allow-Origin coincide con el dominio especificado en la solicitud original. Si coincide, la solicitud tiene éxito. Si no hay coincidencia, o si el encabezado Access-Control-Allow-Origin no está presente en la respuesta, la solicitud falla.

Solicitudes verificadas previamente

Una solicitud tiene verificación previa si se cumple alguna de las siguientes circunstancias:

  • Usa métodos distintos de GET, HEAD o POST.
  • Usa el método POST con un Content-Type distinto de text/plain, application/x-www-form-urlencoded o multipart/form-data.
  • Establece encabezados personalizados. Por ejemplo, X-PINGOTHER.

En una solicitud con verificación previa, se completan los siguientes pasos primero. Si esto se realiza correctamente, luego sigue el siguiente proceso, que es el mismo de una solicitud simple:

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

  2. Cloud Storage responde con los valores de los métodos y encabezados de HTTP que permite el recurso de destino. Si alguno de los valores de método o encabezado en la solicitud de verificación previa no se encuentran en el conjunto de métodos y encabezados que permite el recurso de destino, la solicitud falla y la solicitud principal no se envía.

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

Compatibilidad de Cloud Storage con CORS

Cloud Storage te permite establecer configuraciones de CORS a nivel del bucket. Los extremos de la API de JSON y la API de XML controlan las solicitudes de CORS y muestran encabezados de respuesta de manera diferente. Comprende estos comportamientos para configurar tus buckets de manera eficaz:

  • En los extremos de la API de JSON, siempre se permiten las solicitudes de CORS y se muestran valores predeterminados en los encabezados de respuesta de CORS, sin importar la configuración establecida en el bucket.

  • En los extremos de la API de XML, solo se permiten solicitudes de CORS basadas en la configuración del bucket y se muestran valores de encabezado de CORS específicos en respuesta a esa configuración.

  • En el extremo de descarga del navegador autenticado storage.cloud.google.com, no se permiten las solicitudes de CORS. Ten en cuenta que la consola de Google Cloud proporciona este extremo para el vínculo de URL pública de cada objeto.

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

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

Para obtener información sobre las URL de solicitud a la API de XML, consulta Solicita extremos.

Componentes de una configuración de CORS

Cuando usas la API de XML, los valores que estableces en la configuración de CORS del depósito determinan los encabezados de CORS que muestra Cloud Storage en una respuesta HTTP. Cuando usas la API de JSON, Cloud Storage no evalúa la configuración de tu bucket y, en su lugar, muestra los 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 de XML y JSON. Para obtener información sobre cómo se usan estos campos, consulta Ejemplos de configuración de CORS.

Campo1 Descripción Comportamiento de respuesta de la API de XML Comportamiento de respuesta de la API de JSON
origin Especifica los orígenes que deseas permitir para el uso compartido de recursos entre dominios con este bucket de Cloud Storage. Por ejemplo, https://origin1.example.com. Si el origen en la solicitud de un navegador coincide con un origen en tu configuración de CORS, Cloud Storage muestra 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 otorgue acceso a todos los orígenes: <Origin>*</Origin>. Cloud Storage muestra el encabezado Access-Control-Allow-Origin configurado en el origen de la solicitud.
method

Especifica los métodos de HTTP que deseas permitir para el uso compartido de recursos entre dominios con este bucket de Cloud Storage. El valor se muestra en el encabezado Access-Control-Allow-Methods en respuesta a solicitudes con verificación previa exitosas.

Dado que OPTIONS es un método estándar que los navegadores usan para iniciar solicitudes con verificación previa, no debes especificar OPTIONS en tu configuración de CORS.

Cloud Storage admite los siguientes métodos: DELETE, GET, HEAD, POST y PUT.

Cloud Storage compara los métodos enviados desde el navegador en el encabezado Access-Control-Request-Methods con la configuración de CORS del bucket. Si no hay coincidencia, Cloud Storage muestra un código de respuesta 200 sin encabezados de respuesta de CORS.

 Cloud Storage muestra el encabezado Access-Control-Allow-Methods establecido en los siguientes métodos: DELETE, GET, HEAD, PATCH, POST, PUT.
responseHeader Especifica qué encabezados deseas permitir para el uso compartido de recursos entre dominios con este bucket de Cloud Storage. El valor se muestra en el encabezado Access-Control-Allow-Headers en respuesta a solicitudes con verificación previa exitosas. Para las solicitudes con verificación previa, Cloud Storage compara los encabezados enviados desde el navegador en el encabezado Access-Control-Request-Headers con la configuración de CORS del bucket. Si no hay coincidencia, Cloud Storage no muestra encabezados de respuesta de CORS. Cloud Storage muestra el encabezado Access-Control-Allow-Headers establecido igual a los valores especificados por el encabezado Access-Control-Request-Headers.
maxAgeSeconds (opcional) Especifica la cantidad de segundos que el navegador tiene permitido realizar solicitudes antes de que deba repetir la solicitud de verificación preliminar. Esto también se conoce como hora de vencimiento de la caché. Este valor se muestra en el encabezado Access-Control-Max-Age en las respuestas a las solicitudes con verificación previa. Por ejemplo, 3600 establece la hora de vencimiento de la caché en 1 hora. Cloud Storage muestra el encabezado Access-Control-Max-Age con la hora de vencimiento de la caché especificada. Si omites este campo, Cloud Storage muestra el valor predeterminado de 3600. Cloud Storage muestra el encabezado Access-Control-Max-Age con el valor predeterminado de 3600.

1 Los nombres documentados en la columna Campo son específicos de la API de JSON. Cuando uses la API de XML para establecer una configuración de CORS, usa el formato específico de XML.

Cómo especificar varios orígenes, métodos o encabezados

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

  • Cuando usas la API de JSON, puedes especificar varios orígenes, métodos o encabezados con un array separado por comas. Por ejemplo, "method": ["GET", "PUT"].

  • Cuando usas la API de XML, puedes especificar varios orígenes, métodos o encabezados con elementos separados. Por ejemplo:

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

  • Para permitir que se realicen solicitudes desde cualquier origen, establece el origen en el comodín *. Por ejemplo, "origin": ["*"] en la API de JSON o <Origin>*</Origin> en la API de XML. Si bien este origen es útil para probar parámetros de configuración, en la mayoría de los casos, preferirás restringir los orígenes de las solicitudes a fin de evitar el uso no deseado de tus recursos.

Consideraciones adicionales

En la siguiente tabla, se describen las consideraciones para realizar solicitudes con credenciales o encabezados de control de acceso:

Propiedad o encabezado Descripción Comportamiento de respuesta de la API de XML Comportamiento de respuesta de la API de JSON
Credenciales Cookies, encabezados de autorización o certificados de cliente TLS. Cloud Storage nunca muestra el encabezado Access-Control-Allow-Credentials. La API de XML no admite las credenciales de CORS.

Para solicitudes simples, si se aprueba la solicitud de CORS, el encabezado Access-Control-Allow-Credentials se establece en “true”.

Para las solicitudes con validación previa, si Access-Control-Request-Method está vacío, Cloud Storage establece Access-Control-Allow-Credentials en “true” y rechaza la solicitud con 404 - Not Found.
Encabezados expuestos Para las solicitudes con verificación previa, el encabezado de la solicitud Access-Control-Request-Headers indica qué encabezados puede incluir una solicitud de CORS futura. El encabezado de respuesta Access-Control-Expose-Headers se incluye en la respuesta del servidor e indica al cliente qué encabezados se pueden exponer. En solicitudes simples, Access-Control-Expose-Headers enumera los valores de los encabezados de respuesta en la configuración de CORS. En solicitudes simples, Access-Control-Expose-Headers muestra los valores especificados en Access-Control-Request-Headers si forman parte de una lista de encabezados HTTP comunes.

Permite que los buckets accedan a recursos externos

A veces, es posible que desees permitir que las secuencias de comandos alojadas en Cloud Storage accedan a los recursos estáticos alojados en un sitio web externo a Cloud Storage. En esta situación, el sitio web entrega encabezados de CORS para permitir el acceso al contenido de storage.googleapis.com.

Como práctica recomendada, debes dedicar un bucket específico para este acceso a los datos. Esta estrategia evita que tu sitio exponga de forma involuntaria los recursos estáticos en todo storage.googleapis.com. Por ejemplo, si deseas dedicar un bucket llamado mybucket para el acceso a los datos, debes hacer que el sitio web entregue el encabezado de 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 cliente

La mayoría de los navegadores usan el objeto XMLHttpRequest para realizar una solicitud de dominio cruzado. XMLHttpRequest se encarga del trabajo de insertar los encabezados correctos y manejar la interacción de CORS con el servidor. No necesitas agregar ningún código nuevo para aprovechar la compatibilidad de los buckets de Cloud Storage con CORS.

¿Qué sigue?