Compartilhamento de recursos entre origens (CORS)

Configuração Amostras de configuração

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 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 anterior, é 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 componentes 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á corespondê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. É possível definir uma configuração do CORS para um bucket usando várias ferramentas. No entanto, diferentes endpoints do Cloud Storage lidam com solicitações de CORS de maneiras diferentes:

  • Os endpoints da API JSON sempre permitem solicitações de CORS e retornam valores padrão nos cabeçalhos de resposta do CORS, independentemente da configuração definida no bucket.

  • Os endpoints da API XML permitem apenas solicitações de CORS com base na configuração do bucket e retornam valores de cabeçalho específicos de CORS em resposta a essa configuração.

  • O endpoint de download do navegador autenticado storage.cloud.google.com não permite solicitações de CORS. O console do Google 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.

Componentes de uma configuração do CORS

Ao usar a API XML, os valores definidos na configuração do CORS do bucket determinam os cabeçalhos do CORS retornados pelo Cloud Storage em uma resposta HTTP. Ao usar a API JSON, o Cloud Storage não avalia a configuração do bucket e retorna valores de cabeçalho padrão.

A tabela a seguir descreve os campos em uma configuração do CORS e o comportamento de resposta das APIs XML e JSON. Para saber como esses campos são usados, consulte Exemplos de configuração do CORS.

Campo1 Descrição Comportamento de resposta da API XML Comportamento de resposta da API JSON
origin 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.
method

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.
responseHeader Especifique 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.
maxAgeSeconds (opcional) Especifique o número de segundos que o navegador tem permissão para fazer solicitações antes de repetir a solicitação de simulação. 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.

1 Os nomes documentados na coluna "Campo" são específicos da API JSON. Ao usar a API XML para definir uma configuração do 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 em uma configuração do CORS, consulte a lista a seguir:

  • Ao usar a API JSON, você pode especificar várias origens, métodos ou cabeçalhos usando uma matriz separada por vírgulas. Por exemplo, "method": ["GET", "PUT"]

  • Ao usar a API XML, você pode especificar várias origens, métodos ou cabeçalhos usando elementos separados. Exemplo:

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

  • Defina-a como * para permitir que sejam feitas solicitações a partir de qualquer origem. Por exemplo, "origin": ["*"] na API JSON ou <Origin>*</Origin> na API XML. Embora essa origem seja útil para testar configurações, na maioria dos casos, convém restringir as origens das solicitações para evitar o uso indesejado dos recursos.

Outras considerações

A tabela a seguir descreve as considerações ao fazer solicitações usando credenciais ou cabeçalhos de controle de acesso:

Propriedade ou cabeçalho Descrição Comportamento de resposta da API XML Comportamento de resposta da API JSON
Credenciais Cookies, cabeçalhos de autorização ou certificados do cliente TLS. O Cloud Storage nunca retorna o cabeçalho Access-Control-Allow-Credentials. As credenciais do CORS não são compatíveis com a API XML.

Em solicitações simples, se a solicitação do CORS for aprovada, 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 Para solicitações de simulação, o cabeçalho de solicitação Access-Control-Request-Headers indica quais cabeçalhos uma solicitação de CORS futura pode incluir. O cabeçalho de resposta Access-Control-Expose-Headers está incluído na resposta do servidor e indica ao cliente quais cabeçalhos podem ser expostos. 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.

Como permitir que os buckets acessem recursos externos

Às vezes, é possível permitir que scripts hospedados no Cloud Storage acessem recursos estáticos hospedados em um site externo ao Cloud Storage. Nesse cenário, o site veicula cabeçalhos CORS para que o conteúdo em storage.googleapis.com tenha acesso permitido.

Como prática recomendada, dedique um bucket específico para esse acesso de dados. Essa abordagem impede a superexposição inadvertida de recursos estáticos do site a todo o storage.googleapis.com. Por exemplo, se você quiser dedicar um bucket chamado mybucket para o acesso a dados, faça com que o site exiba o cabeçalho CORS Access-Control-Allow-Origin: https://mybucket.storage.googleapis.com em vez de Access-Control-Allow-Origin: https://storage.googleapis.com.

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