Compartilhamento de recursos entre origens (CORS)

Acessar exemplos

A política de mesma origem é uma política de segurança aplicada em aplicativos da Web do lado do cliente (como navegadores da Web) para evitar interações entre recursos de origens diferentes. Além de ser útil para impedir comportamentos maliciosos, essa medida de segurança também impede interações legítimas entre origens conhecidas. Por exemplo, um script em uma página hospedada no App Engine em example.appspot.com talvez precise usar recursos armazenados em um bucket do Cloud Storage em example.storage.googleapis.com. No entanto, por serem duas origens diferentes na perspectiva do navegador, ele não permitirá que um script de example.appspot.com busque recursos em example.storage.googleapis.com.

A especificação Compartilhamento de recursos entre origens (CORS) foi desenvolvida pelo World Wide Web Consortium (W3C) para contornar essa limitação. O Cloud Storage é compatível com essa especificação e permite configurar os buckets para serem compatíveis com CORS. Continuando com o exemplo acima, é possível configurar o bucket example.storage.googleapis.com para que um navegador compartilhe os recursos dele com scripts de example.appspot.com.

Para mais informações sobre os elementos de configuração do CORS, consulte Definir o CORS de buckets.

Como funciona o CORS

Há dois tipos de solicitações de CORS, simples e simulada. Uma solicitação simples pode ser iniciada diretamente. Uma solicitação simulada precisa enviar uma solicitação preliminar "de simulação" ao servidor para conseguir permissão antes que a solicitação principal possa continuar. Uma solicitação será simulada quando alguma das circunstâncias a seguir for verdadeira:

  • Ela usa métodos diferentes de GET, HEAD ou POST.
  • Ela usa o método POST com um Content-Type diferente de text/plain, application/x-www-form-urlencoded ou multipart/form-data.
  • Ela define cabeçalhos personalizados. Por exemplo, X-PINGOTHER.

O processo a seguir ocorre quando um navegador faz uma solicitação simples ao Cloud Storage:

  1. O navegador adiciona o cabeçalho Origin à solicitação. O cabeçalho Origin contém a origem do recurso que procura compartilhar os recursos do bucket do Cloud Storage, como Origin:https://www.example.appspot.com.

  2. O Cloud Storage compara o método HTTP da solicitação e o valor do cabeçalho Origin com as informações de Métodos e Origens na configuração do CORS do bucket de destino para ver se há correspondências. Se houver, o Cloud Storage incluirá o cabeçalho Access-Control-Allow-Origin na resposta. O cabeçalho Access-Control-Allow-Origin contém o valor do cabeçalho Origin da solicitação inicial.

  3. O navegador recebe a resposta e verifica se o valor Access-Control-Allow-Origin corresponde ao domínio especificado na solicitação original. Se corresponderem, a solicitação será bem-sucedida. Do contrário ou se o cabeçalho Access-Control-Allow-Origin não estiver presente na resposta, a solicitação falhará.

Uma solicitação simulada executa primeiro as etapas a seguir. Se for bem-sucedida, ela segue o mesmo processo que uma solicitação simples:

  1. O navegador envia uma solicitação OPTIONS que contém o Requested Method e os Requested Headers da solicitação principal.

  2. O Cloud Storage responde com os valores dos métodos e cabeçalhos HTTP permitidos pelo recurso de destino. Se algum dos valores de método ou cabeçalho na solicitação de confirmação não estiver no conjunto de métodos e cabeçalhos permitidos pelo recurso de destino, a solicitação apresentará falha e a solicitação principal não será enviada.

Esta é uma descrição simplificada do CORS. Leia uma descrição mais completa na especificação Buscar.

Compatibilidade do CORS com o Cloud Storage

O Cloud Storage permite definir uma configuração do CORS apenas no nível do bucket. Para definir a configuração do CORS de um bucket, use a ferramenta de linha de comando gsutil, a API XML ou a API JSON. No entanto, a configuração do CORS se aplica apenas às solicitações da API XML.

Diferentes endpoints do Cloud Storage lidam com solicitações de CORS das seguintes maneiras:

  • Os endpoints da API JSON permitem solicitações de CORS, independentemente da configuração do CORS no bucket de destino.
  • Os endpoints da API XML aceitam solicitações de CORS com base na configuração do CORS no bucket de destino.
  • O endpoint de download do navegador autenticado storage.cloud.google.com não permite solicitações de CORS. O Console do Cloud fornece esse endpoint para o link de URL público de cada objeto.

É possível usar um dos URLs de solicitação da API XML a seguir para obter uma resposta do Cloud Storage que contenha os cabeçalhos do CORS:

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

Para informações sobre URLs de solicitação da API XML, consulte Solicitar pontos de extremidade.

Elementos de uma configuração do CORS

Os valores definidos na configuração do CORS do bucket determinam os cabeçalhos do CORS retornados pelo Cloud Storage em uma resposta HTTP:

Campo Descrição Comportamento de resposta da API XML Comportamento de resposta da API JSON
Origem Especifique as origens que você quer permitir para o compartilhamento de recursos entre origens com esse bucket do Cloud Storage. Por exemplo, https://origin1.example.com. Se a origem na solicitação de um navegador corresponder a uma origem na configuração do CORS, o Cloud Storage retornará Access-Control-Allow-Origin ao navegador. Se não houver correspondência, o Cloud Storage não incluirá Access-Control-Allow-Origin na resposta. É possível fornecer um valor curinga que conceda acesso a todas as origens: <Origin>*</Origin>. O Cloud Storage retorna o cabeçalho Access-Control-Allow-Origin definido para a origem da solicitação.
Métodos

Especifique os métodos HTTP que você quer permitir para o compartilhamento de recursos entre origens com esse bucket do Cloud Storage. O valor é retornado no cabeçalho Access-Control-Allow-Methods em resposta a solicitações simuladas bem-sucedidas.

Como OPTIONS é um método padrão que os navegadores usam para iniciar solicitações simuladas, não especifique OPTIONS na configuração do CORS.

O Cloud Storage é compatível com os seguintes métodos: DELETE, GET, HEAD, POST, PUT.

O Cloud Storage verifica os métodos enviados do navegador no cabeçalho Access-Control-Request-Methods em relação à configuração do CORS do bucket. Se não houver correspondência, o Cloud Storage retornará um código de resposta 200 sem cabeçalhos de resposta do CORS.

O Cloud Storage retorna o cabeçalho Access-Control-Allow-Methods definido para os seguintes métodos: DELETE, GET, HEAD, PATCH, POST, PUT.
Cabeçalhos de resposta O campo do cabeçalho de resposta especifica quais cabeçalhos você quer permitir para o compartilhamento de recursos entre origens com esse bucket do Cloud Storage. O valor é retornado no cabeçalho Access-Control-Allow-Headers em resposta a solicitações simuladas bem-sucedidas. Nas solicitações simuladas, o Cloud Storage verifica os cabeçalhos enviados do navegador no cabeçalho Access-Control-Request-Headers em relação à configuração do CORS do bucket. Se não houver correspondência, o Cloud Storage não retornará cabeçalhos de resposta do CORS. O Cloud Storage retorna o cabeçalho Access-Control-Allow-Headers definido como igual aos valores especificados pelo cabeçalho Access-Control-Request-Headers.
Idade máxima em segundos (opcional) O campo MaxAgeSec especifica o número de segundos em que um navegador pode fazer solicitações antes que precise repetir a solicitação simulada. Isso também é conhecido como tempo de expiração do cache. Esse valor é retornado no cabeçalho Access-Control-Max-Age em respostas a solicitações simuladas. Por exemplo, 3600 define o tempo de expiração do cache como 1 hora. O Cloud Storage retorna o cabeçalho Access-Control-Max-Age com o tempo de expiração do cache especificado. Se este campo for omitido, o Cloud Storage retornará o valor padrão 3600. O Cloud Storage retorna o cabeçalho Access-Control-Max-Age com o valor padrão 3600.
Outras considerações
Credenciais No momento, o Cloud Storage não aceita as credenciais para o CORS. O Cloud Storage nunca retorna o cabeçalho Access-Control-Allow-Credentials.

Em solicitações simples, se a solicitação do CORS for aprovada e válida, o cabeçalho Access-Control-Allow-Credentials será definido como verdadeiro.

Em solicitações simuladas, se Access-Control-Request-Method estiver vazio, o Cloud Storage definirá Access-Control-Allow-Credentials como verdadeiro e rejeitará a solicitação com 404 - Not Found.

Cabeçalhos expostos O cabeçalho de resposta Access-Control-Expose-Headers lista nomes de cabeçalho que ficam expostos como parte da resposta. Em solicitações simples, Access-Control-Expose-Headers lista os valores dos cabeçalhos de resposta na configuração do CORS. Em solicitações simples, Access-Control-Expose-Headers retorna os valores especificados em Access-Control-Request-Headers se fizerem parte de uma lista de cabeçalhos HTTP comuns.

Suporte ao CORS do lado do cliente

A maioria dos navegadores usa o objeto XMLHttpRequest para fazer uma solicitação entre domínios. O XMLHttpRequest cuida de todo o trabalho de inserir os cabeçalhos certos e lidar com a interação do CORS com o servidor. Não é necessário adicionar nenhum código novo para aproveitar a compatibilidade com o CORS em buckets do Cloud Storage.

A seguir