URLs assinados

Nesta página, você terá uma visão geral dos URLs assinados, usados para conceder acesso com limite de tempo a recursos para qualquer pessoa que tenha o URL, independentemente de ter 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 outras formas de controlar o acesso a intervalos 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 de usuário ou de serviço que precisa ter permissão suficiente para fazer a solicitação. 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 típica 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. Qualquer pessoa que tenha o URL pode acessar o recurso até que o URL expire. Você especifica o prazo de validade ao criar o URL assinado.

Opções para gerar um URL assinado

O Cloud Storage é compatível com vários métodos para gerar um URL assinado:

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

  • Assinatura V2 com autenticação de conta de serviço: para mais informações sobre esse mecanismo de assinatura, clique aqui.

  • 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, apontar para o host storage.googleapis.com e usar as credenciais do Google HMAC 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-central-1%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 leitura do objeto cat.jpeg no intervalo example-bucket. Os parâmetros de consulta que fazem com que esse seja um URL assinado são os seguintes:

  • 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 hora em que o URL assinado se tornou utilizável, no formato básico ISO 8601 YYYYMMDD'T'HHMMSS'Z'.

  • 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.

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

  • X-Goog-Signature: a string de autenticação que permitiu o acesso a cat.jpeg para solicitações usando esse URL assinado.

Como usar URLs assinados com uploads recuperáveis

Ao usar URLs assinados com uploads recuperáveis de objetos no seu intervalo, você só precisa usar o URL assinado na solicitação POST inicial. Nenhum dado é carregado na solicitação POST. Em vez disso, a solicitação retorna um URI de sessão que é usado em solicitações PUT subsequentes para fazer upload de dados. Como o URI da sessão é, na realidade, um token de autenticação, as solicitações PUT não precisam usar o URL assinado original. Esse comportamento permite que a solicitação POST seja feita pelo servidor. Assim, os clientes não precisam lidar com URLs assinados.

Os uploads recuperáveis são fixados na região em que são iniciados. Por exemplo, se você criar um URL de upload recuperável nos EUA e entregá-lo a um cliente na Ásia, o upload ainda passará pelos EUA. A realização de um upload recuperável em uma região onde ele não foi iniciado pode causar uploads lentos. Para evitar isso, tenha a solicitação POST inicial construída e assinada pelo servidor, mas forneça o URL assinado ao cliente para que o upload seja iniciado a partir da localização dele. Uma vez iniciado, o cliente pode usar o URI de sessão resultante normalmente para fazer solicitações PUT que não precisam ser assinadas.

Considerações sobre URLs assinados

Ao trabalhar com URLs assinados, tenha isto em mente:

  • Geralmente, os URLs assinados podem ser feitos para qualquer solicitação da API XML. No entanto, as bibliotecas cliente do Cloud Storage para Node.js atualmente 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 intervalo.

  • As bibliotecas cliente do Cloud Storage para Python e Go atualmente não aceitam URLs assinados por V4.

  • Parâmetros de string de consulta como response-content-disposition e response-content-type não são verificados pela assinatura. Para forçar um Content-Disposition ou Content-Type na resposta, defina esses parâmetros nos metadados do objeto.

  • 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 da ID da conta de serviço também é aceito.

Solicitações canônicas

A solicitação canônica é aquela que os usuários precisam fazer ao usar o URL assinado. Ela inclui informações como o verbo HTTP, parâmetros de string de consulta e cabeçalhos que precisam ser usados em uma solicitação que usa seu URL assinado, bem como o objeto, intervalo ou outro recurso a que o URL assinado concede acesso.

Verbos HTTP

Os URLs assinados podem ser usados com os seguintes verbos HTTP:

Caminho do recurso

O caminho para o recurso a que o URL assinado será aplicado está incluído na solicitação canônica. Esse caminho é tudo o que segue o nome do host, mas precede qualquer string de consulta.

Por exemplo, se o URL do Cloud Storage for https://storage.googleapis.com/example-bucket/cat-pics/tabby.jpeg?userProject=my-project, o caminho para o recurso será /example-bucket/cat-pics/tabby.jpeg.

Se você usa um URL alternativo do Cloud Storage, como https://example-bucket.storage.googleapis.com/cat-pics/tabby.jpeg?userProject=my-project, o caminho para o recurso será /cat-pics/tabby.jpeg.

Para conhecer outros endpoints de URL que podem ser usados com URLs assinados, consulte Endpoints de solicitação da API XML.

Ao definir o caminho do recurso, é preciso codificar por cento os seguintes caracteres reservados: ?=!#$&'()*+,:;@[].". Qualquer outra codificação por cento usada no URL também precisa ser incluída no caminho do recurso.

String de consulta

Estão incluídos na solicitação canônica os parâmetros de string de consulta que precisam fazer parte de qualquer solicitação que use o URL assinado. A string de consulta é tudo o que está após o ponto de interrogação (?) no final do caminho do recurso.

Por exemplo, se o URL do Cloud Storage for https://storage.googleapis.com/example-bucket/cat-pics/tabby.jpeg?userProject=my-project, a string de consulta será userProject=my-project.

Na solicitação canônica, a string de consulta precisa classificar todos os parâmetros pelo nome usando uma classificação lexicográfica por pontuação do código, e todos os parâmetros precisam estar separados por &.

Parâmetros obrigatórios da string de consulta

Muitos parâmetros de string de consulta, como alt, são adicionados conforme necessário. No entanto, os parâmetros de string de consulta a seguir são obrigatórios em todos os URLs assinados:

  • X-Goog-Algorithm: o algoritmo usado para assinar o URL. Os valores válidos são GOOG4-RSA-SHA256 e GOOG4-HMAC-SHA256.
  • X-Goog-Credential: as credenciais usadas para assinar o URL. Elas consistem em um autorizador e um escopo de credencial fornecido no formato [AUTHORIZER]%2F[CREDENTIAL_SCOPE]. O autorizador pode ser um nome de conta de serviço ou uma chave de acesso HMAC.
  • X-Goog-Date: a data e hora atuais, no formato básico ISO 8601 YYYYMMDD'T'HHMMSS'Z'.
  • X-Goog-Expires: o tempo de vida do URL assinado, medido em segundos a partir do valor em X-Goog-Date.
  • X-Goog-SignedHeaders: uma lista separada por ponto-e-vírgula de nomes de cabeçalhos que precisam ser incluídos em qualquer solicitação usando o URL assinado. host precisa estar entre esses cabeçalhos.
  • X-Goog-Signature: a assinatura que autentica a solicitação.

Cabeçalhos

Estão incluídos na solicitação canônica os cabeçalhos que precisam fazer parte de qualquer solicitação que use o URL assinado, incluindo cabeçalhos personalizados e cabeçalhos de extensão que começam com x-goog. Você especifica os cabeçalhos em várias partes da solicitação canônica:

  1. Especifique os nomes dos cabeçalhos no parâmetro de string de consulta X-Goog-SignedHeaders, com cada nome separado por ;.
  2. Especifique o cabeçalho name:value após a parte da string de consulta da solicitação canônica, com cada par separado por uma nova linha (\n).
  3. Especifique os nomes dos cabeçalhos em uma nova linha após a lista de pares de name:value, com cada nome separado por ;.

Ao especificar os pares de name:value para cabeçalhos, tenha em mente o seguinte:

  • Escreva todos os nomes de cabeçalho em minúsculas.
  • Classifique todos os cabeçalhos por nome usando uma classificação lexicográfica por pontuação de código.
  • Elimine nomes de cabeçalho duplicados criando um nome de cabeçalho com uma lista de valores separados por vírgula. Veja bem se não há espaços em branco entre os valores e se a ordem da lista separada por vírgula corresponda à ordem em que os cabeçalhos aparecem em sua solicitação. Para mais informações, consulte a seção 3.2 da RFC 7230 (em inglês).
  • Substitua qualquer espaço em branco ou novas linhas (CRLF ou LF) por um único espaço. Para mais informações sobre espaços em branco, consulte a seção 3.2.4 da RFC 7230 (em inglês).
  • Remova qualquer espaço em branco em volta dos dois pontos que aparecem após o nome do cabeçalho.

    Por exemplo, usar o cabeçalho personalizado x-goog-acl: private sem remover o espaço depois dos dois-pontos retorna um erro 403 Forbidden, porque a assinatura da solicitação que você calcula não corresponde à assinatura que o Google calcula.

Por exemplo, levando em consideração o seguinte conjunto de cabeçalhos:

host: storage.googleapis.com
content-type: text/plain
x-goog-meta-reviewer: jane
x-goog-meta-reviewer: john

A construção na solicitação canônica seria:

content-type:text/plain
host:storage.googleapis.com
x-goog-meta-reviewer:jane,john

Cabeçalhos obrigatórios

A maioria dos cabeçalhos, como content-type e cabeçalhos de extensão, são adicionados conforme necessário. No entanto, o cabeçalho a seguir é obrigatório em todos os URLs assinados:

  • host: o URI usado para acessar o Cloud Storage.

Além disso, os cabeçalhos a seguir não podem ser usados em solicitações que usam um URL assinado, a menos que sejam explicitamente especificados na solicitação canônica.

  • x-goog-project-id
  • x-goog-copy-source
  • x-goog-metadata-directive
  • x-amz-copy-source
  • x-amz-metadata-directive

Escopo da credencial

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

[DATE]/[LOCATION]/storage/goog4_request
  • [DATE]: data formatada como AAAAMMDD e precisa corresponder ao dia usado na string a ser assinada.
  • [LOCATION]: a região em que o recurso reside ou será criado. Para recursos do Cloud Storage, o valor de [LOCATION] é arbitrário. O parâmetro [LOCATION] existe para manter a compatibilidade com o Amazon Simple Storage Service (Amazon S3).
  • storage: o nome do serviço.
  • goog4_request: o tipo de URL assinado.

Exemplo: 20181102/us/storage/goog4_request

Como assinar strings com as ferramentas do Google Cloud Platform

Ao gerar um URL assinado usando um programa, uma opção para assinar a string é usar as ferramentas fornecidas pelo GCP.

Serviço App Identity do App Engine

A assinatura em um aplicativo do App Engine usa o serviço App Identity, que usa as credenciais da conta de serviço do App Engine. Por exemplo, usando a API App Identity para Python, é possível:

  • usar google.appengine.api.app_identity.sign_blob() para assinar os bytes de sua string construída, fornecendo a Signature que você precisa ao montar o URL assinado;

  • usar google.appengine.api.app_identity.get_service_account_name() para recuperar um nome de conta de serviço, que é o GoogleAccessId necessário ao montar o URL assinado.

O App Engine também fornece suporte em outras linguagens:

O serviço App Identity faz a rotação das chaves privadas ao assinar os blobs. Os URLs assinados gerados pelo serviço App Identity são válidos por pelo menos uma hora e são melhor utilizados para acesso de curta duração aos recursos.

signBlob do IAM

A assinatura pode ser realizada usando o método signBlob do IAM.

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.