Compartilhamento de recursos entre origens (CORS)

Configuração Amostras de configuração

O Compartilhamento de recursos entre origens (CORS) permite que aplicativos da Web do lado do cliente acessem recursos de origens diferentes. O Cloud Storage é compatível com a especificação CORS, permitindo configurar os buckets para compartilhar recursos com segurança com scripts de outras origens. Por exemplo, é possível usar o CORS para permitir que o aplicativo da Web https://example-app.appspot.com acesse um recurso na origem https://example-data.storage.googleapis.com.

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

Como funciona o CORS

Use o CORS quando quiser que seu site busque arquivos, imagens ou scripts diretamente de um bucket do Cloud Storage usando uma solicitação baseada em navegador.

Permitir o acesso entre domínios

Por padrão, os navegadores da Web aplicam uma medida de segurança chamada política de mesma origem. A política de mesma origem impede que um script em um site interaja com recursos em um domínio diferente. Embora isso proteja os usuários contra sites maliciosos, também bloqueia solicitações legítimas. Por exemplo, se o aplicativo da Web https://example-app.appspot.com tentar acessar um recurso na origem https://example-data.storage.googleapis.com, o navegador vai bloquear a solicitação por padrão porque os domínios não correspondem.

A especificação do CORS oferece uma maneira para os servidores informarem ao navegador: "Confio neste domínio específico, então permita a solicitação".

O Cloud Storage permite definir uma configuração do CORS no bucket. Quando configurado, o Cloud Storage envia cabeçalhos HTTP específicos de volta ao navegador (como Access-Control-Allow-Origin), que autorizam o navegador a compartilhar os recursos do bucket com seu aplicativo da Web.

Tipos de solicitação

As solicitações de CORS funcionam de duas maneiras: simples e simulada. Uma solicitação simples é processada diretamente, enquanto uma solicitação simulada primeiro envia uma solicitação preliminar para obter permissão.

Solicitações simples

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-app.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á.

Solicitações de simulação

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

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 simulação não estiver no conjunto de métodos e cabeçalhos permitidos pelo recurso de destino, a solicitação vai falhar e a solicitação principal não será enviada.

Para uma descrição mais completa das solicitações do CORS, leia a especificação Fetch.

Compatibilidade do CORS com o Cloud Storage

O Cloud Storage permite definir configurações do CORS no nível do bucket. Os endpoints da API JSON e da API XML processam solicitações de CORS e retornam cabeçalhos de resposta de maneira diferente. Entenda esses comportamentos para configurar seus agrupamentos de forma eficaz:

  • 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 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 origem como o caractere curinga * 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