Partilha de recursos de origem cruzada (CORS)

Configuração Exemplos de configuração

A política de mesma origem é uma política de segurança aplicada em aplicações Web do lado do cliente (como navegadores de Internet) para impedir interações entre recursos de origens diferentes. Embora seja útil para evitar comportamentos maliciosos, esta medida de segurança também impede interações legítimas entre origens conhecidas. Por exemplo, um script numa página alojada em example.appspot.com pode ter de usar recursos armazenados num contentor do Cloud Storage em example.storage.googleapis.com. No entanto, como se tratam de duas origens diferentes na perspetiva do navegador, o navegador não permite que um script de example.appspot.com obtenha recursos de example.storage.googleapis.com.

A especificação de partilha de recursos de origem cruzada (CORS) foi desenvolvida pelo World Wide Web Consortium (W3C) para contornar esta limitação. O Cloud Storage suporta esta especificação, permitindo-lhe configurar os seus contentores para suportarem CORS. Continuando com o exemplo anterior, pode configurar o contentor example.storage.googleapis.com para que um navegador possa partilhar os respetivos recursos com scripts de example.appspot.com.

Para mais informações sobre os componentes de configuração da CORS, consulte o artigo Defina a CORS do contentor.

Como funciona o CORS

Existem dois tipos de pedidos CORS: simples e de verificação prévia. Pode iniciar diretamente um pedido simples. Um pedido de verificação prévia tem de enviar um pedido preliminar de "verificação prévia" ao servidor para obter autorização antes de o pedido principal poder avançar. Um pedido é pré-validado se alguma das seguintes circunstâncias for verdadeira:

  • Usa métodos que não sejam GET, HEAD ou POST.
  • Usa o método POST com um Content-Type diferente de text/plain, application/x-www-form-urlencoded ou multipart/form-data.
  • Define cabeçalhos personalizados. Por exemplo, X-PINGOTHER.

O processo seguinte ocorre quando um navegador faz um pedido simples ao Cloud Storage:

  1. O navegador adiciona o cabeçalho Origin ao pedido. O cabeçalho Origin contém a origem do recurso que procura partilhar os recursos do contentor do Cloud Storage, por exemplo, Origin:https://www.example.appspot.com.

  2. O Cloud Storage compara o método HTTP do pedido e o valor do cabeçalho Origin com as informações Methods e Origins na configuração CORS do contentor de destino para ver se existem correspondências. Se existirem, o Cloud Storage inclui o cabeçalho Access-Control-Allow-Origin na respetiva resposta. O cabeçalho Access-Control-Allow-Origin contém o valor do cabeçalho Origin do pedido inicial.

  3. O navegador recebe a resposta e verifica se o valor Access-Control-Allow-Origin corresponde ao domínio especificado no pedido original. Se corresponderem, o pedido é bem-sucedido. Se não corresponderem ou se o cabeçalho Access-Control-Allow-Origin não estiver presente na resposta, o pedido falha.

Um pedido de pré-voo executa primeiro os seguintes passos. Se for bem-sucedida, segue o mesmo processo que um pedido simples:

  1. O navegador envia um pedido OPTIONS que contém o Requested Method e o Requested Headers do pedido principal.

  2. O Cloud Storage responde com os valores dos métodos HTTP e dos cabeçalhos permitidos pelo recurso segmentado. Se algum dos valores do método ou do cabeçalho no pedido de verificação prévia não estiver no conjunto de métodos e cabeçalhos permitidos pelo recurso segmentado, o pedido falha e o pedido principal não é enviado.

Esta é uma descrição simplificada do CORS. Para uma descrição mais completa, leia a especificação Fetch.

Compatibilidade com CORS do Cloud Storage

O Cloud Storage permite-lhe definir uma configuração de CORS apenas ao nível do contentor. Pode configurar uma configuração CORS para um contentor através de várias ferramentas. No entanto, os diferentes pontos finais do Cloud Storage processam os pedidos CORS de formas diferentes:

  • Os pontos finais da API JSON permitem sempre pedidos CORS e devolvem valores predefinidos nos cabeçalhos de resposta CORS, independentemente da configuração definida no contentor.

  • Os pontos finais da API XML só permitem pedidos CORS com base na configuração no contentor e devolvem valores de cabeçalhos CORS específicos em resposta a essa configuração.

  • O ponto final de transferência do navegador autenticado storage.cloud.google.com não permite pedidos CORS. Tenha em atenção que a Google Cloud consola fornece este ponto final para o link do URL público de cada objeto.

Pode usar qualquer um dos seguintes URLs de solicitação da API XML para obter uma resposta do Cloud Storage que contenha os cabeçalhos CORS:

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

Para obter informações sobre URLs de pedidos da API XML, consulte o artigo Pontos finais de pedidos.

Componentes de uma configuração de CORS

Quando usa a API XML, os valores que define na configuração de CORS do seu contentor determinam os cabeçalhos de CORS que o Cloud Storage devolve numa resposta HTTP. Quando usa a API JSON, o Cloud Storage não avalia a configuração do seu contentor e, em vez disso, devolve valores de cabeçalho predefinidos.

A tabela seguinte descreve os campos numa configuração CORS e o comportamento de resposta das APIs XML e JSON. Para saber como estes campos são usados, consulte os exemplos de configuração de CORS.

Campo1 Descrição Comportamento da resposta da API XML Comportamento da resposta da API JSON
origin Especifique as origens que quer permitir para a partilha de recursos de origem cruzada com este contentor do Cloud Storage. Por exemplo, https://origin1.example.com. Se a origem num pedido do navegador corresponder a uma origem na sua configuração de CORS, o Cloud Storage devolve Access-Control-Allow-Origin ao navegador. Se não existir uma correspondência, o armazenamento na nuvem não inclui Access-Control-Allow-Origin na resposta. Pode fornecer um valor universal que concede acesso a todas as origens: <Origin>*</Origin>. O Cloud Storage devolve o cabeçalho Access-Control-Allow-Origin definido para a origem do pedido.
method

Especifique os métodos HTTP que quer permitir para a partilha de recursos de origens cruzadas com este contentor do Cloud Storage. O valor é devolvido no cabeçalho Access-Control-Allow-Methods em resposta a pedidos de pré-envio bem-sucedidos.

Uma vez que OPTIONS é um método padrão que os navegadores usam para iniciar pedidos de verificação prévia, não deve especificar OPTIONS na configuração do CORS.

O Cloud Storage suporta os seguintes métodos: DELETE, GET, HEAD, POST, PUT.

O armazenamento na nuvem verifica os métodos enviados do navegador no cabeçalho Access-Control-Request-Methods em relação à configuração de CORS do contentor. Se não existir uma correspondência, o Cloud Storage devolve um código de resposta 200 sem cabeçalhos de resposta de CORS.

 O Cloud Storage devolve o cabeçalho Access-Control-Allow-Methods definido para os seguintes métodos: DELETE, GET, HEAD, PATCH, POST, PUT.
responseHeader Especifique os cabeçalhos que quer permitir para a partilha de recursos de origem cruzada com este contentor do Cloud Storage. O valor é devolvido no cabeçalho Access-Control-Allow-Headers em resposta a pedidos de pré-voo bem-sucedidos. Para pedidos de verificação prévia, o Cloud Storage verifica os cabeçalhos enviados a partir do navegador no cabeçalho Access-Control-Request-Headers em comparação com a configuração de CORS do contentor. Se não houver correspondência, o Cloud Storage não devolve cabeçalhos de resposta CORS. O Cloud Storage devolve o cabeçalho Access-Control-Allow-Headers definido como igual aos valores especificados pelo cabeçalho Access-Control-Request-Headers.
maxAgeSeconds (opcional) Especifique o número de segundos que o navegador tem permissão para fazer pedidos antes de ter de repetir o pedido de pré-voo. Isto também é conhecido como o tempo de expiração da cache. Este valor é devolvido no cabeçalho Access-Control-Max-Age em respostas a pedidos de verificação prévia. Por exemplo, 3600 define o tempo de expiração da cache para 1 hora. O Cloud Storage devolve o cabeçalho Access-Control-Max-Age com o tempo de expiração da cache especificado. Se omitir este campo, o Cloud Storage devolve o valor predefinido de 3600. O Cloud Storage devolve o cabeçalho Access-Control-Max-Age com o valor predefinido de 3600.

1 Os nomes documentados na coluna Campo são específicos da API JSON. Quando usar a API XML para definir uma configuração de CORS, use o formato específico de XML.

Especificar várias origens, métodos ou cabeçalhos

Para saber como definir várias origens, métodos ou cabeçalhos numa configuração de CORS, consulte a seguinte lista:

  • Quando usa a API JSON, pode especificar várias origens, métodos ou cabeçalhos através de uma matriz separada por vírgulas. Por exemplo, "method": ["GET", "PUT"].

  • Quando usa a API XML, pode especificar várias origens, métodos ou cabeçalhos usando elementos separados. Por exemplo:

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

  • Para permitir que os pedidos sejam feitos a partir de qualquer origem, defina a origem como *. Por exemplo, "origin": ["*"] na API JSON ou <Origin>*</Origin> na API XML. Embora esta origem seja útil para testar configurações, na maioria dos casos, é recomendável restringir as origens dos pedidos para evitar a utilização indesejada dos seus recursos.

Considerações adicionais

A tabela seguinte descreve as considerações ao fazer pedidos com credenciais ou cabeçalhos de controlo de acesso:

Propriedade ou cabeçalho Descrição Comportamento da resposta da API XML Comportamento da resposta da API JSON
Credenciais Cookies, cabeçalhos de autorização ou certificados de cliente TLS. O Cloud Storage nunca devolve o cabeçalho Access-Control-Allow-Credentials. As credenciais de CORS não são suportadas pela API XML.

Para pedidos simples, se o pedido CORS for aprovado, o cabeçalho Access-Control-Allow-Credentials é definido como verdadeiro.

Para pedidos de pré-validação, se Access-Control-Request-Method estiver vazio, o Cloud Storage define Access-Control-Allow-Credentials como verdadeiro e rejeita o pedido com 404 - Not Found.
Cabeçalhos expostos Para pedidos de verificação prévia, o cabeçalho do pedido Access-Control-Request-Headers indica que cabeçalhos um futuro pedido CORS pode incluir. O cabeçalho de resposta Access-Control-Expose-Headers está incluído na resposta do servidor e indica ao cliente que cabeçalhos podem ser expostos. Para pedidos simples, Access-Control-Expose-Headers apresenta os valores dos cabeçalhos de resposta na sua configuração de CORS. Para pedidos simples, Access-Control-Expose-Headers devolve os valores especificados em Access-Control-Request-Headers se fizerem parte de uma lista de cabeçalhos HTTP comuns.

Permitir que os contentores acedam a recursos externos

Por vezes, pode querer permitir que os scripts alojados no Cloud Storage acedam a recursos estáticos alojados num Website externo ao Cloud Storage. Neste cenário, o Website disponibiliza cabeçalhos CORS para que o conteúdo em storage.googleapis.com tenha acesso permitido.

Recomendamos que dedique um contentor específico para este acesso aos dados. Esta abordagem impede que o seu site exponha inadvertidamente recursos estáticos a todos os utilizadores do storage.googleapis.com. Por exemplo, se quiser dedicar um contentor denominado mybucket para acesso aos dados, deve fazer com que o Website publique o cabeçalho CORS Access-Control-Allow-Origin: https://mybucket.storage.googleapis.com em vez de Access-Control-Allow-Origin: https://storage.googleapis.com.

Compatibilidade com CORS do lado do cliente

A maioria dos navegadores usa o objeto XMLHttpRequest para fazer um pedido entre domínios. XMLHttpRequest encarrega-se de todo o trabalho de inserir os cabeçalhos certos e processar a interação CORS com o servidor. Não tem de adicionar novo código para tirar partido da compatibilidade com CORS nos contentores do Cloud Storage.

O que se segue?