URLs assinados

Nesta página, você terá uma visão geral dos URLs assinados, que dão acesso por tempo limitado a um recurso específico do Cloud Storage. Qualquer pessoa que tiver o URL assinado poderá usá-lo enquanto ele estiver ativo, mesmo sem uma conta do Google. Para saber como criar um URL assinado, consulte Processo de assinatura V4 com ferramentas do Cloud Storage e Processo de assinatura V4 com seu próprio programa. Para aprender outras maneiras de controlar o acesso a buckets e objetos, consulte Visão geral do controle de acesso.

Visão geral

Um URL assinado é um URL que fornece permissão e tempo limitados para fazer uma solicitação. Os URLs assinados contêm informações de autenticação na string de consulta, permitindo que usuários sem credenciais executem ações específicas em um recurso.

  • Ao gerar um URL assinado, você especifica uma conta que precisa ter permissão suficiente para fazer a solicitação que o URL assinado vai fazer.

    • Na maioria dos casos, a conta é uma conta de serviço.

    • Nos casos em que você cria o programa para gerar URLs assinados, é possível usar uma conta de usuário se ela tiver uma chave HMAC associada.

Depois que a geração for concluída, qualquer pessoa que tenha o URL assinado poderá usá-lo para executar as ações especificadas, como a leitura de um objeto, dentro do período especificado.

Quando usar um URL assinado?

Em alguns cenários, talvez você não queira exigir que seus usuários tenham uma Conta do Google para acessar o Cloud Storage, mas ainda queira controlar o acesso usando a lógica específica do aplicativo. A maneira comum de abordar esse caso de uso é fornecer um URL assinado a um usuário, o que permite a ele ler, gravar ou excluir o acesso a esse recurso por um tempo limitado. Você especifica um prazo de validade ao criar o URL assinado. Qualquer pessoa que tenha o URL pode acessar o recurso até que o prazo de validade do URL seja atingido ou a chave usada para assinar o URL seja revezada.

Os usos mais comuns para URLs assinados são uploads e downloads, porque, nessas solicitações, os dados do objeto são movidos entre os solicitantes e o Cloud Storage. Na maioria dos casos, como copiar objetos, escrever objetos, excluir objetos ou editar metadados, criar um URL assinado e fornecê-lo a alguém para ser usado é uma etapa extra desnecessária. Em vez disso, é preciso considerar um design em que a entidade responsável por criar o URL assinado faça a solicitação desejada ao Cloud Storage.

Opções para gerar um URL assinado

O Cloud Storage é compatível com vários métodos de geração de um URL assinado:

  • Assinatura V4 com autenticação de conta de serviço: esse mecanismo de assinatura é descrito abaixo.

  • Assinatura com autenticação HMAC: se você é um usuário do Amazon Simple Storage Service (Amazon S3), é possível usar seus fluxos de trabalho atuais para gerar URLs assinados para o Cloud Storage. Basta especificar os recursos do Cloud Storage, direcionar para o host storage.googleapis.com e usar as credenciais HMAC do Cloud Storage no processo de geração do URL assinado.

Exemplo de URL assinado

Veja a seguir um exemplo de URL assinado que foi criado com o processo de assinatura V4 e autenticação da conta de serviço:

https://storage.googleapis.com/example-bucket/cat.jpeg?X-Goog-Algorithm=
GOOG4-RSA-SHA256&X-Goog-Credential=example%40example-project.iam.gserviceaccount.com
%2F20181026%2Fus-central1%2Fstorage%2Fgoog4_request&X-Goog-Date=20181026T18
1309Z&X-Goog-Expires=900&X-Goog-SignedHeaders=host&X-Goog-Signature=247a2aa45f16
9edf4d187d54e7cc46e4731b1e6273242c4f4c39a1d2507a0e58706e25e3a85a7dbb891d62afa849
6def8e260c1db863d9ace85ff0a184b894b117fe46d1225c82f2aa19efd52cf21d3e2022b3b868dc
c1aca2741951ed5bf3bb25a34f5e9316a2841e8ff4c530b22ceaa1c5ce09c7cbb5732631510c2058
0e61723f5594de3aea497f195456a2ff2bdd0d13bad47289d8611b6f9cfeef0c46c91a455b94e90a
66924f722292d21e24d31dcfb38ce0c0f353ffa5a9756fc2a9f2b40bc2113206a81e324fc4fd6823
a29163fa845c8ae7eca1fcf6e5bb48b3200983c56c5ca81fffb151cca7402beddfc4a76b13344703
2ea7abedc098d2eb14a7

Esse URL assinado forneceu acesso para ler o objeto cat.jpeg no bucket example-bucket. Veja a seguir os parâmetros de consulta que tornam esse URL assinado:

  • X-Goog-Algorithm: o algoritmo usado para assinar o URL.

  • X-Goog-Credential: informações sobre as credenciais usadas para criar o URL assinado.

  • X-Goog-Date: a data e a hora em que o URL assinado se tornou utilizável, no formato básico YYYYMMDD'T'HHMMSS'Z' do ISO 8601 (em inglês).

  • X-Goog-Expires: o período em que o URL assinado permaneceu válido, medido em segundos a partir do valor em X-Goog-Date. No exemplo, o URL assinado expira em 15 minutos. O maior valor de expiração é de 604.800 segundos (sete dias).

  • X-Goog-SignedHeaders: cabeçalhos que devem ser incluídos como parte de qualquer solicitação que usou o URL assinado.

  • X-Goog-Signature: a string de autenticação que permitiu às solicitações que usam esse URL assinado acessar cat.jpeg.

Como usar URLs assinados com uploads retomáveis

Geralmente, a criação de URLs assinados para uploads retomáveis é desnecessária, porque, após a solicitação para iniciar o upload, as solicitações PUT subsequentes para fazer upload dos dados do objeto usam um URI de sessão, que atua como um token de autenticação. Isso significa que as solicitações PUT não usam URLs assinados.

Embora seja possível criar e usar um URL assinado para a solicitação POST inicial para iniciar o upload, na maioria dos casos, o servidor pode iniciar o upload retomável. Em seguida, o servidor envia o URI da sessão para o cliente para realizar o upload. Isso evita a complexidade de fazer com que o servidor crie um URL assinado, assim como a complexidade de fazer com que o cliente processe o URL assinado e inicie o upload retomável.

Assim como os URLs assinados, um URI de sessão pode ser usado por qualquer pessoa que tenha acesso a ele para fazer o upload de dados. Não se esqueça de transmitir o URI da sessão por HTTPS ao fornecê-lo a um cliente.

Considerações sobre URLs assinados

Ao trabalhar com URLs assinados, tenha isto em mente:

  • Os URLs assinados só podem ser usados apenas para acessar os recursos no Cloud Storage por meio de endpoints da API XML.

  • Geralmente, os URLs assinados podem ser feitos para qualquer solicitação da API XML. No entanto, há duas exceções:

    • Os URLs assinados que usam assinaturas V4 não podem ser usados em solicitações cujo corpo usa uma codificação em blocos.

    • Atualmente, as bibliotecas de cliente do Cloud Storage para Node.js só podem criar URLs assinados para objetos individuais. Por exemplo, não é possível usá-las para criar URLs assinados para listar objetos em um bucket.

  • Ao especificar credenciais, é recomendável que você identifique sua conta de serviço usando o endereço de e-mail dela. No entanto, o uso do ID da conta de serviço também é aceito.

  • Não se esqueça de omitir o cabeçalho de autorização das solicitações que usam um URL assinado. Se ambos forem usados, o Cloud Storage poderá se autenticar nas credenciais fornecidas no cabeçalho e não no URL assinado. Isso pode permitir mais acesso aos recursos do que você pretendia.

Solicitações canônicas

Os URLs assinados usam solicitações canônicas como parte das informações codificadas no parâmetro de string de consulta X-Goog-Signature. Ao criar um URL assinado com as ferramentas do Cloud Storage, a solicitação canônica exigida é criada e incorporada automaticamente. No entanto, ao criar um URL assinado com seu próprio programa, você precisará definir a solicitação canônica e usá-la para criar uma assinatura.

Escopo da credencial

O escopo da credencial aparece na string a ser assinada e no parâmetro de string de consulta X-Goog-Credential.

A seguir