Criar uma SAS de serviço

Uma SAS (assinatura de acesso compartilhado) de serviço delega acesso a um recurso em apenas um dos serviços de armazenamento: Armazenamento de Blobs do Azure, Armazenamento de Filas do Azure, Armazenamento de Tabelas do Azure ou Arquivos do Azure. O URI de uma SAS no nível do serviço consiste no URI para o recurso para o qual a SAS delegará o acesso, seguido pelo token SAS.

O token SAS é a cadeia de caracteres de consulta que inclui todas as informações necessárias para autorizar uma solicitação. O token especifica o recurso que um cliente pode acessar, as permissões concedidas e o período de tempo durante o qual a assinatura é válida.

Uma SAS também pode especificar o endereço IP com suporte ou o intervalo de endereços do qual as solicitações podem ser originadas, o protocolo com suporte com o qual uma solicitação pode ser feita ou um identificador de política de acesso opcional associado à solicitação.

Por fim, cada token SAS inclui uma assinatura.

Cuidado

As assinaturas de acesso compartilhado são chaves que concedem permissões aos recursos de armazenamento e você deve protegê-las da mesma forma que protegeria uma chave de conta. É importante proteger um SAS contra uso malicioso ou não intencional. Use discrição ao distribuir um SAS e tenha um plano em vigor para revogar um SAS comprometido. As operações que usam assinaturas de acesso compartilhado devem ser executadas somente em uma conexão HTTPS, e as URIs SAS devem ser distribuídas somente em uma conexão segura, como HTTPS.

Autorizar uma SAS de serviço

Você protege uma SAS de conta usando uma chave de conta de armazenamento. Quando você cria uma SAS de conta, seu aplicativo cliente deve possuir a chave da conta.

Para usar as credenciais do Azure Active Directory (Azure AD) para proteger uma SAS para um contêiner ou blob, crie uma SAS de delegação de usuário.

Suporte de SAS de serviço para acesso no escopo do diretório

Uma SAS de serviço dá suporte ao escopo do diretório (sr=d) quando a versão de autorização (sv) for 2020-02-10 ou posterior e um namespace hierárquico estiver habilitado. A semântica para escopo de diretório (sr=d) é semelhante àquelas para escopo de contêiner (sr=c), exceto que o acesso é restrito a um diretório e a quaisquer arquivos e subdiretórios dentro dele. Quando sr=d especificado, o sdd parâmetro de consulta também é necessário.

O formato cadeia de caracteres para assinar para autorização versão 2020-02-10 é inalterado.

Construir uma SAS de serviço

A imagem a seguir representa as partes do URI de assinatura de acesso compartilhado. As partes necessárias aparecem em laranja. Os campos que compõem o token SAS são descritos nas seções subsequentes.

Diagrama dos elementos de parâmetro de uma URL de assinatura de acesso compartilhado.

As seções a seguir descrevem como especificar os parâmetros que compõem o token SAS de serviço.

Especificar o signedVersion campo

O signedVersion campo (sv) contém a versão de serviço da assinatura de acesso compartilhado. Esse valor especifica a versão da autorização de Chave Compartilhada usada por essa assinatura de acesso compartilhado (no signature campo). O valor também especifica a versão de serviço para solicitações feitas com essa assinatura de acesso compartilhado.

Para obter informações sobre qual versão é usada quando você executa solicitações por meio de uma assinatura de acesso compartilhado, consulte Controle de versão para serviços de Armazenamento do Azure.

Para obter informações sobre como esse parâmetro afeta a autorização de solicitações feitas com uma assinatura de acesso compartilhado, consulte o acesso do Delegado com uma assinatura de acesso compartilhado.

Nome do campo Parâmetro de consulta Descrição
signedVersion sv Obrigatórios. Com suporte na versão 2012-02-12 e posterior. A versão do serviço de armazenamento a ser usada para autorizar e manipular solicitações que você faz com essa assinatura de acesso compartilhado. Para obter mais informações, consulte Controle de versão para serviços de Armazenamento do Azure.

Determinar a versão de uma solicitação SAS herdada

Em cenários herdados em que signedVersion não é usado, o Armazenamento de Blobs aplica regras para determinar a versão. Para obter mais informações sobre essas regras, consulte Controle de versão para serviços de Armazenamento do Azure.

Importante

O software cliente pode ter um comportamento de protocolo inesperado quando você usa um URI de assinatura de acesso compartilhado que usa uma versão do serviço de armazenamento mais recente que o software cliente. O código que constrói URIs de assinatura de acesso compartilhado deve depender de versões compreendidas pelo software cliente que faz solicitações de serviço de armazenamento.

Especificar o recurso assinado (somente Armazenamento de Blobs)

O campo necessário signedResource (sr) especifica quais recursos podem ser acessados por meio da assinatura de acesso compartilhado. A tabela a seguir descreve como fazer referência a um recurso de blob ou contêiner no token SAS.

Recurso Valor do parâmetro Versões com suporte Descrição
Blob b Tudo Concede acesso ao conteúdo e metadados do blob.
Versão do blob Bv 2018-11-09 e posterior Concede acesso ao conteúdo e metadados da versão do blob, mas não ao blob base.
Instantâneo de blobs bs 2018-11-09 e posterior Concede acesso ao conteúdo e metadados do instantâneo de blob, mas não ao blob base.
Contêiner c Tudo Concede acesso ao conteúdo e metadados de qualquer blob no contêiner e à lista de blobs no contêiner.
Diretório d 2020-02-10 e posterior Concede acesso ao conteúdo e metadados de qualquer blob no diretório e à lista de blobs no diretório, em uma conta de armazenamento com um namespace hierárquico habilitado. Se um diretório for especificado para o signedResource campo, o signedDirectoryDepth parâmetro (sdd) também será necessário. Um diretório sempre é aninhado em um contêiner.

Especificar o recurso assinado (Arquivos do Azure)

Há suporte para SAS para Arquivos do Azure versão 2015-02-21 e posterior.

O campo signedResource especifica quais recursos estão acessíveis pela assinatura de acesso compartilhado. A tabela a seguir descreve como fazer referência a um arquivo ou recurso de compartilhamento no URI.

Nome do campo Parâmetro de consulta Descrição
signedResource sr Obrigatórios.

Especifique f se o recurso compartilhado é um arquivo. Isso concede acesso ao conteúdo e aos metadados do arquivo.

Especifique s se o recurso compartilhado é um compartilhamento. Isso concede acesso ao conteúdo e aos metadados de qualquer arquivo no compartilhamento e à lista de diretórios e arquivos no compartilhamento.

Especificar parâmetros de consulta para substituir cabeçalhos de resposta (Armazenamento de Blobs e somente Arquivos do Azure)

Para definir valores para determinados cabeçalhos de resposta para serem retornados quando a assinatura de acesso compartilhado for usada em uma solicitação, você poderá especificar cabeçalhos de resposta em parâmetros de consulta. Esse recurso tem suporte na versão 2013-08-15 para Armazenamento de Blobs e versão 2015-02-21 para Arquivos do Azure. As assinaturas de acesso compartilhado que usam esse recurso devem incluir o sv parâmetro definido para 2013-08-15 ou posterior para o Armazenamento de Blobs ou para 2015-02-21 ou posterior para Arquivos do Azure.

Os cabeçalhos de resposta e os parâmetros de consulta correspondentes estão listados na tabela a seguir:

Nome do cabeçalho de resposta Parâmetro de consulta de SAS correspondente
Cache-Control rscc
Content-Disposition rscd
Content-Encoding rsce
Content-Language rscl
Content-Type rsct

Por exemplo, se você especificar o rsct=binary parâmetro de consulta em uma assinatura de acesso compartilhado criada com a versão 2013-08-15 ou posterior, o cabeçalho de Content-Type resposta será definido como binary. Esse valor substitui o Content-Type valor de cabeçalho armazenado para o blob para uma solicitação que usa apenas essa assinatura de acesso compartilhado.

Se você criar uma assinatura de acesso compartilhado que especifica cabeçalhos de resposta como parâmetros de consulta, deverá incluí-los no sinal de cadeia de caracteres usado para construir a cadeia de caracteres de assinatura. Para obter mais informações, consulte a seção "Construir a cadeia de caracteres de assinatura" mais adiante neste artigo. Para obter exemplos adicionais, consulte exemplos de SAS de serviço.

Especificar o nome da tabela (somente Armazenamento de Tabelas)

O campo tableName especifica o nome da tabela para compartilhar.

Nome do campo Parâmetro de consulta Descrição
tableName tn Obrigatórios. O nome da tabela a ser compartilhada.

Especificar a política de acesso

A parte da política de acesso do URI indica o período de tempo durante o qual a assinatura de acesso compartilhado é válida e as permissões a serem concedidas ao usuário. As partes do URI que compõem a política de acesso são descritas na tabela a seguir:

Nome do campo Parâmetro de consulta Descrição
signedStart st Opcional. A hora em que a assinatura de acesso compartilhado se torna válida, expressa em um dos formatos UTC ISO 8601 aceitos. Se esse parâmetro for omitido, a hora UTC atual será usada como a hora de início.

Em versões anteriores a 2012-02-12, a duração entre signedStart e signedExpiry não pode exceder uma hora, a menos que uma política de contêiner seja usada. Para obter mais informações sobre formatos UTC aceitos, consulte Formatar valores de data/hora.
signedExpiry se Obrigatórios. A hora em que a assinatura de acesso compartilhado se torna inválida, expressa em um dos formatos UTC ISO 8601 aceitos. Você deve omitir esse campo se ele tiver sido especificado em uma política de acesso armazenado associada. Para obter mais informações sobre formatos UTC aceitos, consulte Formatar valores de data/hora.
signedPermissions1 sp Obrigatórios. As permissões associadas à assinatura de acesso compartilhado. O usuário é restrito a operações permitidas pelas permissões. Você deve omitir esse campo se ele tiver sido especificado em uma política de acesso armazenado associada.
startPk2

startRk2
spk

srk
Somente Armazenamento de Tabelas.

Opcional, mas startPk deve acompanhar startRk. As chaves mínimas de partição e linha que podem ser acessadas com essa assinatura de acesso compartilhado. Os valores da chave são inclusivos. Se eles forem omitidos, não haverá limite inferior nas entidades de tabela que podem ser acessadas.
endPk2

endRk2
epk

erk
Somente Armazenamento de Tabelas.

Opcional, mas endPk deve acompanhar endRk. As chaves máximas de partição e linha que podem ser acessadas com essa assinatura de acesso compartilhado. Os valores da chave são inclusivos. Se forem omitidos, não haverá limite superior nas entidades de tabela que podem ser acessadas.

1 O signedPermissions campo é necessário no URI, a menos que seja especificado como parte de uma política de acesso armazenado.
2 Os startPkcampos , startRke endPkendRk os campos só podem ser especificados em recursos do Armazenamento de Tabelas.

Especificar as permissões

As permissões especificadas para o signedPermissions campo (sp) no token SAS indicam quais operações um cliente pode executar no recurso.

Você pode combinar permissões para permitir que um cliente execute várias operações com a mesma SAS. Ao construir a SAS, você deve incluir permissões na seguinte ordem:

racwdxltmeop

Exemplos de configurações de permissões válidas para um contêiner incluemrw, rd, , rl, wde wlrl. Exemplos de configurações inválidas incluem wr, dre lrdw. Você não pode especificar uma designação de permissão mais de uma vez.

Uma SAS de serviço não pode conceder acesso a determinadas operações:

  • Contêineres, filas e tabelas não podem ser criados, excluídos ou listados.
  • Os metadados e as propriedades do contêiner não podem ser lidos ou gravados.
  • As filas não podem ser limpas e os metadados não podem ser gravados.
  • Os contêineres não podem ser alugados.

Para construir uma SAS que conceda acesso a essas operações, use uma SAS de conta. Para obter mais informações, confira Criar uma SAS de conta.

Importante

As assinaturas de acesso compartilhado são chaves que concedem permissões aos recursos de armazenamento e você deve protegê-las da mesma forma que protegeria uma chave de conta. Execute operações que usam assinaturas de acesso compartilhado somente em uma conexão HTTPS e distribua URIs de assinatura de acesso compartilhado somente em uma conexão segura, como HTTPS.

As permissões com suporte para cada tipo de recurso são descritas nas seções a seguir.

Permissões para um diretório, contêiner ou blob

As permissões com suporte para cada tipo de recurso são descritas na tabela a seguir:

Permissão Símbolo de URI Recurso Suporte à versão Operações permitidas
Ler r Contêiner
Diretório
Blob
Tudo Leia o conteúdo, a lista de bloqueios, as propriedades e os metadados de qualquer blob no contêiner ou diretório. Use um blob como a origem de uma operação de cópia.
Adicionar um Contêiner
Diretório
Blob
Tudo Adicione um bloco a um blob de acréscimo.
Criar c Contêiner
Diretório
Blob
Tudo Escreva um novo blob, instantâneo de um blob ou copie um blob para um novo blob.
Gravar w Contêiner
Diretório
Blob
Tudo Criar ou gravar conteúdo, propriedades, metadados ou lista de bloqueios. Crie um instantâneo ou conceda o blob. Redimensionar o blob (blob da página somente). Use o blob como o destino de uma operação de cópia.
Excluir d Contêiner
Diretório
Blob
Tudo Excluir um blob. Para a versão 2017-07-29 e posterior, a permissão Delete também permite quebrar uma concessão em um blob. Para obter mais informações, consulte a operação de Blob de Concessão .
Excluir versão x Contêiner
Blob
2019-12-12 e posterior Excluir a versão do blob.
Exclusão permanente a Blob 2020-02-10 e posterior Exclua permanentemente um instantâneo ou uma versão do blob.
Lista l Contêiner
Diretório
Tudo Listar blobs de forma não recursiva.
Marcações t Blob 2019-12-12 e posterior Leia ou escreva as marcas em um blob.
Localizar f Contêiner 2019-12-12 e posterior Localize blobs com marcas de índice.
Mover m Contêiner
Diretório
Blob
2020-02-10 e posterior Mova um blob ou um diretório e seu conteúdo para um novo local. Essa operação pode, opcionalmente, ser restrita ao proprietário do diretório filho, diretório ou diretório pai se o saoid parâmetro for incluído no token SAS e o bit pegajoso estiver definido no diretório pai.
Execute (executar) e Contêiner
Diretório
Blob
2020-02-10 e posterior Obtenha as propriedades do sistema e, se o namespace hierárquico estiver habilitado para a conta de armazenamento, obtenha a ACL POSIX de um blob. Se o namespace hierárquico estiver habilitado e o chamador for o proprietário de um blob, essa permissão concederá a capacidade de definir o grupo proprietário, as permissões POSIX e a ACL POSIX do blob. não permite que o chamador leia metadados definidos pelo usuário.
Propriedade o Contêiner
Diretório
Blob
2020-02-10 e posterior Quando o namespace hierárquico está habilitado, essa permissão permite que o chamador defina o proprietário ou o grupo proprietário ou atue como o proprietário ao renomear ou excluir um diretório ou blob dentro de um diretório que tenha o conjunto de bits pegajoso.
Permissões p Contêiner
Diretório
Blob
2020-02-10 e posterior Quando o namespace hierárquico está habilitado, essa permissão permite que o chamador defina permissões e ACLs POSIX em diretórios e blobs.
Definir Política de Imutabilidade i Contêiner
Blob
2020-06-12 e posterior Defina ou exclua a política de imutabilidade ou a retenção legal em um blob.

Permissões para um arquivo

Permissão Símbolo de URI Operações permitidas
Ler r Leia o conteúdo, as propriedades, os metadados. Use o arquivo como a origem de uma operação de cópia.
Criar c Crie um novo arquivo ou copie um arquivo para um novo arquivo.
Gravar w Criar ou gravar conteúdo, propriedades, metadados. Redimensione o arquivo. Use o arquivo como o destino de uma operação de cópia.
Excluir d Excluir o arquivo.

Permissões para um compartilhamento

Permissão Símbolo de URI Operações permitidas
Ler r Leia o conteúdo, as propriedades ou os metadados de qualquer arquivo no compartilhamento. Use qualquer arquivo no compartilhamento como a origem de uma operação de cópia.
Criar c Crie um novo arquivo no compartilhamento ou copie um arquivo para um novo arquivo no compartilhamento.
Gravar w Para qualquer arquivo no compartilhamento, crie ou escreva conteúdo, propriedades ou metadados. Redimensione o arquivo. Use o arquivo como o destino de uma operação de cópia. Observação: você não pode conceder permissões para ler ou gravar propriedades ou metadados de compartilhamento usando uma SAS de serviço. Em vez disso, use uma SAS de conta.
Excluir d Exclua qualquer arquivo no compartilhamento. Observação: você não pode conceder permissões para excluir um compartilhamento usando uma SAS de serviço. Em vez disso, use uma SAS de conta.
Lista l Listar arquivos e diretórios no compartilhamento.

Permissões para uma fila

Permissão Símbolo de URI Operações permitidas
Ler r Ler os metadados e as propriedades, inclusive a contagem de mensagens. Inspecionar mensagens.
Adicionar um Adicionar mensagens à fila.
Atualizar u Atualizar mensagens na fila. Observação: use a permissão Process com Update para que você possa primeiro receber a mensagem que deseja atualizar.
Processo p Receber e excluir mensagens da fila.

Permissões para uma tabela

Permissão Símbolo de URI Operações permitidas
Consulta r Obter entidades e entidades de consulta.
Adicionar um Adicionar entidades. Observação: as permissões adicionar e atualizar são necessárias para operações upsert.
Atualizar u Atualizar entidades. Observação: as permissões adicionar e atualizar são necessárias para operações upsert.
Excluir d Excluir entidades.

Especificar um endereço IP ou intervalo de IP

A partir da versão 2015-04-05, o campo opcional signedIp (sip) especifica um endereço IP público ou um intervalo de endereços IP públicos dos quais aceitar solicitações. Se o endereço IP do qual a solicitação se origina não corresponder ao endereço IP ou intervalo de endereços especificado no token SAS, a solicitação não será autorizada.

Ao especificar um intervalo de endereços IP, observe que o intervalo é inclusivo. Por exemplo, especificar sip=168.1.5.65 ou sip=168.1.5.60-168.1.5.70 na SAS restringe a solicitação a esses endereços IP.

A tabela a seguir descreve se o signedIp campo deve ser incluído em um token SAS para um cenário especificado, com base no ambiente do cliente e no local da conta de armazenamento.

Ambiente do cliente Local da conta de armazenamento Recomendação
Cliente em execução no Azure Na mesma região que o cliente Uma SAS fornecida ao cliente neste cenário não deve incluir um endereço IP de saída para o signedIp campo. As solicitações feitas de dentro da mesma região que usam uma SAS com um endereço IP de saída especificado falharão.

Em vez disso, use uma rede virtual do Azure para gerenciar restrições de segurança de rede. As solicitações para o Armazenamento do Azure de dentro da mesma região sempre ocorrem em um endereço IP privado. Para saber mais, consulte Configurar Redes Virtuais e Firewalls de Armazenamento do Azure.
Cliente em execução no Azure Em uma região diferente do cliente Uma SAS fornecida ao cliente neste cenário pode incluir um endereço IP público ou um intervalo de endereços para o signedIp campo. Uma solicitação feita com a SAS deve se originar do endereço IP especificado ou do intervalo de endereços.
Cliente em execução local ou em um ambiente de nuvem diferente Em qualquer região do Azure Uma SAS fornecida ao cliente neste cenário pode incluir um endereço IP público ou um intervalo de endereços para o signedIp campo. Uma solicitação feita com a SAS deve se originar do endereço IP especificado ou do intervalo de endereços.

Se a solicitação passar por um proxy ou gateway, forneça o endereço IP de saída público desse proxy ou gateway para o signedIp campo.

Especificar o protocolo HTTP

A partir da versão 2015-04-05, o campo opcional signedProtocol (spr) especifica o protocolo permitido para uma solicitação feita com a SAS. Os valores possíveis são HTTPS e HTTP (https,http) ou somente HTTPS (https). O valor padrão é https,http. Observe que somente HTTP não é um valor permitido.

Especificar intervalos de acesso à tabela

Os startPkcampos , startRke endPkendRk os campos definem um intervalo de entidades de tabela associadas a uma assinatura de acesso compartilhado. As consultas de tabela retornam apenas os resultados que estão dentro do intervalo e as tentativas de usar a assinatura de acesso compartilhado para adicionar, atualizar ou excluir entidades fora desse intervalo falharão.

Se startPk for igual endPk, a assinatura de acesso compartilhado autorizará o acesso a entidades em apenas uma partição na tabela.

Se startPk for igual endPk e startRk igual endRk, a assinatura de acesso compartilhado poderá acessar apenas uma entidade em uma partição.

Para entender como esses campos restringem o acesso a entidades em uma tabela, consulte a seguinte tabela:

Campos presentes Escopo da restrição
startPk partitionKey >= startPk
endPk partitionKey <= endPk
startPk, startRk (partitionKey >startPk) || (partitionKey == startPk&& rowKey >= startRk)
endPk, endRk (partitionKey <endPk) || (partitionKey == endPk&& rowKey <= endRk)

Especificar a profundidade do diretório

Quando um namespace hierárquico está habilitado e o signedResource campo especifica um diretório (sr=d), você também deve especificar o signedDirectoryDepth campo (sdd) para indicar o número de subdiretórios no diretório raiz. O valor do sdd campo deve ser um inteiro não negativo.

Por exemplo, o diretório https://{account}.blob.core.windows.net/{container}/ raiz tem uma profundidade de 0. Cada subdiretório dentro do diretório raiz adiciona à profundidade por 1. O diretório https://{account}.blob.core.windows.net/{container}/d1/d2 tem uma profundidade de 2.

Esse campo tem suporte com a versão 2020-02-10 ou posterior.

Especificar o identificador assinado

Ao especificar o signedIdentifier campo no URI, você relaciona a assinatura de acesso compartilhado especificada a uma política de acesso armazenado correspondente. Uma política de acesso armazenada fornece uma medida adicional de controle sobre uma ou mais assinaturas de acesso compartilhado, incluindo a capacidade de revogar a assinatura se for necessário. Cada contêiner, fila, tabela ou compartilhamento pode ter até cinco políticas de acesso armazenadas.

A tabela a seguir descreve como se referir a um identificador assinado no URI:

Nome do campo Parâmetro de consulta Descrição
signedIdentifier si Opcional. Um valor exclusivo de até 64 caracteres que se correlaciona a uma política de acesso especificada para o contêiner, fila ou tabela.

Uma política de acesso armazenado inclui um identificador assinado, um valor de até 64 caracteres exclusivo dentro do recurso. Você pode especificar o valor desse identificador assinado para o signedidentifier campo no URI para a assinatura de acesso compartilhado. Ao especificar um identificador assinado no URI, associe a assinatura à política de acesso armazenada. Para estabelecer uma política de acesso no nível do contêiner usando a API REST, consulte o acesso do Delegado com uma assinatura de acesso compartilhado.

Especificar o escopo de criptografia

Usando o signedEncryptionScope campo no URI, você pode especificar o escopo de criptografia que o aplicativo cliente pode usar. Ele impõe a criptografia do lado do servidor com o escopo de criptografia especificado quando você carrega blobs (PUT) com o token SAS. O GET e o HEAD não serão restritos e executados como antes.

A tabela a seguir descreve como se referir a um escopo de criptografia assinado no URI:

Nome do campo Parâmetro de consulta Descrição
signedEncryptionScope ses Opcional. Indica o escopo de criptografia a ser usado para criptografar o conteúdo da solicitação.

Esse campo tem suporte com a versão 2020-12-06 ou posterior. Se você adicionar a ses versão anterior à com suporte, o serviço retornará o código de resposta de erro 403 (Proibido).

Se você definir o escopo de criptografia padrão para o contêiner ou sistema de arquivos, o parâmetro de ses consulta respeitará a política de criptografia de contêiner. Se houver uma incompatibilidade entre o parâmetro de consulta e x-ms-default-encryption-scope o ses cabeçalho, e o x-ms-deny-encryption-scope-override cabeçalho estiver definido comotrue, o serviço retornará o código de resposta de erro 403 (Proibido).

Quando você fornece o x-ms-encryption-scope cabeçalho e o ses parâmetro de consulta na solicitação PUT, o serviço retorna o código de resposta de erro 400 (Solicitação Incorreta) se houver uma incompatibilidade.

Especificar a assinatura

Use a parte de assinatura do URI para autorizar a solicitação feita com a assinatura de acesso compartilhado. O Armazenamento do Azure usa um esquema de autorização de Chave Compartilhada para autorizar uma SAS de serviço.

A tabela a seguir descreve como especificar a assinatura no URI:

Nome do campo Parâmetro de consulta Descrição
signature sig A cadeia de caracteres a assinar é uma cadeia de caracteres exclusiva construída a partir dos campos e que deve ser verificada para autorizar a solicitação. A assinatura é um HMAC (código de autenticação de mensagem baseado em hash) que você calcula sobre a cadeia de caracteres para assinar e a chave usando o algoritmo SHA256 e, em seguida, codifica usando a codificação Base64.

Construir a cadeia de caracteres de assinatura

Para construir a cadeia de caracteres de assinatura de uma assinatura de acesso compartilhado, primeiro construa a cadeia de caracteres a partir dos campos que compõem a solicitação, codifique a cadeia de caracteres como UTF-8 e, em seguida, compute a assinatura usando o algoritmo HMAC-SHA256. Os campos incluídos na cadeia de caracteres a assinar devem ser decodificados por URL.

Versão 2020-12-06 e posterior

A versão 2020-12-06 adiciona suporte para o campo de escopo de criptografia assinado. Para construir a cadeia de caracteres a assinar para recursos do Armazenamento de Blobs, use o seguinte formato:

StringToSign = signedPermissions + "\n" +  
               signedStart + "\n" +  
               signedExpiry + "\n" +  
               canonicalizedResource + "\n" +  
               signedIdentifier + "\n" +  
               signedIP + "\n" +  
               signedProtocol + "\n" +  
               signedVersion + "\n" +  
               signedResource + "\n" +
               signedSnapshotTime + "\n" +
               signedEncryptionScope + "\n" +
               rscc + "\n" +  
               rscd + "\n" +  
               rsce + "\n" +  
               rscl + "\n" +  
Versão 2018-11-09 e posterior

A versão 2018-11-09 adiciona suporte para o recurso assinado e campos de tempo de instantâneo de blob assinados. Esses campos devem ser incluídos na cadeia de caracteres para assinar. Para construir a cadeia de caracteres a assinar para recursos do Armazenamento de Blobs, use o seguinte formato:

StringToSign = signedPermissions + "\n" +  
               signedStart + "\n" +  
               signedExpiry + "\n" +  
               canonicalizedResource + "\n" +  
               signedIdentifier + "\n" +  
               signedIP + "\n" +  
               signedProtocol + "\n" +  
               signedVersion + "\n" +  
               signedResource + "\n"
               signedSnapshotTime + "\n" +
               rscc + "\n" +  
               rscd + "\n" +  
               rsce + "\n" +  
               rscl + "\n" +  
               rsct  
Versão 2015-04-05 e posterior

A versão 2015-04-05 adiciona suporte para os campos de PROTOCOLO IP assinado e assinados. Esses campos devem ser incluídos na cadeia de caracteres para assinar. Para construir a cadeia de caracteres para assinar para o Armazenamento de Blobs ou recursos de Arquivos do Azure, use o seguinte formato:

StringToSign = signedPermissions + "\n" +  
               signedStart + "\n" +  
               signedExpiry + "\n" +  
               canonicalizedResource + "\n" +  
               signedIdentifier + "\n" +  
               signedIP + "\n" +  
               signedProtocol + "\n" +  
               signedVersion + "\n" +  
               rscc + "\n" +  
               rscd + "\n" +  
               rsce + "\n" +  
               rscl + "\n" +  
               rsct  

Para construir a cadeia de caracteres a assinar para recursos do Armazenamento de Tabelas, use o seguinte formato:

StringToSign = signedPermissions + "\n" +  
               signedStart + "\n" +  
               signedExpiry + "\n" +  
               canonicalizedResource + "\n" +  
               signedIdentifier + "\n" +  
               signedIP + "\n" +  
               signedProtocol + "\n" +  
               signedVersion + "\n" +  
               startingPartitionKey + "\n"  
               startingRowKey + "\n"  
               endingPartitionKey + "\n"  
               endingRowKey  
  

Para construir a cadeia de caracteres a assinar para recursos do Armazenamento de Filas, use o seguinte formato:

StringToSign = signedPermissions + "\n" +  
               signedStart + "\n" +  
               signedExpiry + "\n" +  
               canonicalizedResource + "\n" +  
               signedIdentifier + "\n" +  
               signedIP + "\n" +  
               signedProtocol + "\n" +  
               signedVersion  
  
Versão 2013-08-15 a 2015-02-21

Para construir a cadeia de caracteres para assinar para o Armazenamento de Blobs ou Arquivos do Azure recursos usando a versão 2013-08-15 a 2015-02-21, use o formato a seguir. Para Arquivos do Azure, há suporte para SAS a partir da versão 2015-02-21.

StringToSign = signedPermissions + "\n" +  
               signedStart + "\n" +  
               signedExpiry + "\n" +  
               canonicalizedResource + "\n" +  
               signedIdentifier + "\n" +  
               signedVersion + "\n" +  
               rscc + "\n" +  
               rscd + "\n" +  
               rsce + "\n" +  
               rscl + "\n" +  
               rsct  

Para construir a string-to-sign para uma tabela, use o seguinte formato:

StringToSign = signedPermissions + "\n" +  
               signedStart + "\n" +  
               signedExpiry + "\n" +  
               canonicalizedResource + "\n" +  
               signedIdentifier + "\n" +  
               signedVersion + "\n" +  
               startPk + "\n" +  
               startRk + "\n" +  
               endPk + "\n" +  
               endRk  
  

Para construir a cadeia de caracteres para assinar para uma fila, use o seguinte formato:

StringToSign = signedPermissions + "\n" +  
               signedStart + "\n" +  
               signedExpiry + "\n" +  
               canonicalizedResource + "\n" +  
               signedIdentifier + "\n" +  
               signedVersion 
Versão 2012-02-12

Para construir a cadeia de caracteres para assinar os recursos do Armazenamento de Blobs para a versão 2012-02-12, use o seguinte formato:

StringToSign = signedPermissions + "\n" +  
               signedStart + "\n" +  
               signedExpiry + "\n" +  
               canonicalizedResource + "\n" +  
               signedIdentifier + "\n" +  
               signedVersion  
Versões anteriores a 2012-02-12

Para construir a cadeia de caracteres para assinar recursos do Armazenamento de Blobs para versões anteriores a 2012-02-12, use o seguinte formato:

StringToSign = signedPermissions + "\n" +  
               signedStart + "\n" +  
               signedExpiry + "\n" +  
               canonicalizedResource + "\n" +  
               signedIdentifier  
  

Ao construir a cadeia de caracteres a ser assinada, tenha em mente o seguinte:

  • Se um campo for opcional e não fornecido como parte da solicitação, especifique uma cadeia de caracteres vazia para esse campo. Inclua o caractere de nova linha (\n) depois da cadeia de caracteres vazia.

  • A cadeia de caracteres a assinar para uma tabela deve incluir os parâmetros adicionais, mesmo que sejam cadeias de caracteres vazias.

  • A signedpermission parte da cadeia de caracteres deve incluir as designações de permissão em uma ordem fixa específica para cada tipo de recurso. Qualquer combinação dessas permissões é aceitável, mas a ordem das letras de permissão deve corresponder à ordem na tabela a seguir.

    Tipo de recurso Ordem das permissões
    Blob racwd
    Contêiner racwdl
    Fila raup
    Arquivo rcwd
    Compartilhar rcwdl
    Tabela raud

    Por exemplo, exemplos de configurações de permissões válidas para um contêiner incluemrw, rd, , rl, wde wlrl. Exemplos de configurações inválidas incluem wr, dre lrdw. Não é permitido especificar uma designação de permissão mais de uma vez.

  • Forneça um valor para a signedIdentifier parte da cadeia de caracteres se você estiver associando a solicitação a uma política de acesso armazenada.

  • Uma assinatura de acesso compartilhado que especifica uma versão do serviço de armazenamento anterior a 2012-02-12 pode compartilhar apenas um blob ou contêiner e deve omitir signedVersion e o caractere newline antes dele.

  • A parte de canonicalizedResource da cadeia de caracteres é um caminho canônico para o recurso assinado. Ele deve incluir o nome do serviço (Armazenamento de Blobs, Armazenamento de Tabelas, Armazenamento de Filas ou Arquivos do Azure) para a versão 2015-02-21 ou posterior, o nome da conta de armazenamento e o nome do recurso e deve ser decodificado por URL. Os nomes dos blobs devem incluir o contêiner do blob. Os nomes de tabela devem ser minúsculos.

A cadeia de caracteres de recurso canônica para um contêiner, fila, tabela ou compartilhamento de arquivos deve omitir a barra à direita (/) para uma SAS que fornece acesso a esse objeto.

Os exemplos a seguir mostram como construir a canonicalizedResource parte da cadeia de caracteres, dependendo do tipo de recurso.

Contêineres

Para a versão 2015-02-21 e posterior:

URL = https://myaccount.blob.core.windows.net/music  
canonicalizedResource = "/blob/myaccount/music"  

Para versões anteriores a 2015-02-21:

URL = https://myaccount.blob.core.windows.net/music
canonicalizedResource = "/myaccount/music"  

Blobs

Para a versão 2015-02-21 e posterior:

URL = https://myaccount.blob.core.windows.net/music/intro.mp3  
canonicalizedResource = "/blob/myaccount/music/intro.mp3"  

Para versões anteriores a 2015-02-21:

URL = https://myaccount.blob.core.windows.net/music/intro.mp3
canonicalizedResource = "/myaccount/music/intro.mp3"  

Compartilhamentos de Arquivos

URL = https://myaccount.file.core.windows.net/music
canonicalizedResource = "/file/myaccount/music"  

Arquivos

URL = https://myaccount.file.core.windows.net/music/intro.mp3
canonicalizedResource = "/file/myaccount/music/intro.mp3"  

Filas

Para a versão 2015-02-21 e posterior:

URL = https://myaccount.queue.core.windows.net/thumbnails  
canonicalizedResource = "/queue/myaccount/thumbnails"  

Para versões anteriores a 2015-02-21:

URL = https://myaccount.queue.core.windows.net/thumbnails  
canonicalizedResource = "/myaccount/thumbnails"  

Tabelas

Se o recurso assinado for uma tabela, verifique se o nome da tabela está em letras minúsculas no formato canônico.

Para a versão 2015-02-21 e posterior:

URL = https://myaccount.table.core.windows.net/Employees(PartitionKey='Jeff',RowKey='Price')  
canonicalizedResource = "/table/myaccount/employees"  

Para versões anteriores a 2015-02-21:

URL = https://myaccount.table.core.windows.net/Employees(PartitionKey='Jeff',RowKey='Price')  
canonicalizedResource = "/myaccount/employees"  

Tempo de vida e revogação de uma assinatura de acesso compartilhado

As assinaturas de acesso compartilhado concedem aos usuários direitos para armazenar recursos da conta de armazenamento. Quando estiver planejando usar uma SAS, pense no tempo de vida da SAS e se seu aplicativo pode precisar revogar direitos de acesso em determinadas circunstâncias.

SAS ad hoc versus política de acesso armazenado

Uma SAS de serviço pode usar uma das duas formas:

  • SAS ad hoc: quando você cria uma SAS ad hoc, a hora de início, a hora de expiração e as permissões para a SAS são especificadas no URI SAS (ou implícitas, se a hora de início for omitida). Qualquer tipo de SAS pode ser uma SAS ad hoc.

    Você pode gerenciar o tempo de vida de uma SAS ad hoc usando o signedExpiry campo. Se você quiser continuar concedendo a um cliente acesso ao recurso após o tempo de expiração, deverá emitir uma nova assinatura. Recomendamos que você mantenha o tempo de vida de uma assinatura de acesso compartilhado curto. Antes da versão 2012-02-12, uma assinatura de acesso compartilhado não associada a uma política de acesso armazenado não poderia ter um período ativo que excedesse uma hora.

  • SAS com política de acesso armazenado: uma política de acesso armazenado é definida em um contêiner de recursos, que pode ser um contêiner de blob, tabela, fila ou compartilhamento de arquivos. Você pode usar a política de acesso armazenado para gerenciar restrições para uma ou mais assinaturas de acesso compartilhado. Quando você associa uma SAS a uma política de acesso armazenada, a SAS herda as restrições (ou seja, a hora de início, a hora de expiração e as permissões) definidas para a política de acesso armazenada.

    A política de acesso armazenada é representada pelo campo signedIdentifier no URI. Uma política de acesso armazenada fornece uma medida adicional de controle sobre uma ou mais assinaturas de acesso compartilhado, incluindo a capacidade de revogar a assinatura se for necessário.

Revogar uma SAS

Como um URI SAS é uma URL, qualquer pessoa que obtém a SAS pode usá-la, independentemente de quem o criou originalmente. Se uma SAS for publicada publicamente, ela poderá ser usada por qualquer pessoa no mundo. Uma SAS concede acesso a recursos a qualquer pessoa que o possua até que uma das quatro coisas aconteça:

  • O tempo de expiração especificado em uma SAS ad hoc é atingido.

  • O tempo de expiração especificado na política de acesso armazenado referenciada pela SAS será atingido, se uma política de acesso armazenado for referenciada e a política de acesso especificar um tempo de expiração.

    O tempo de expiração pode ser atingido porque o intervalo passa ou porque você modificou a política de acesso armazenado para ter um tempo de expiração no passado, que é uma maneira de revogar a SAS.

  • A política de acesso armazenado referenciada pela SAS é excluída, o que revoga a SAS. Se o Armazenamento do Azure não conseguir localizar a política de acesso armazenada especificada na assinatura de acesso compartilhado, o cliente não poderá acessar o recurso indicado pelo URI.

    Se você recriar a política de acesso armazenada com exatamente o mesmo nome da política excluída, todos os tokens SAS existentes serão novamente válidos, de acordo com as permissões associadas a essa política de acesso armazenada. Isso pressupõe que o tempo de expiração na SAS não tenha passado. Se você pretende revogar a SAS, use um nome diferente ao recriar a política de acesso com um tempo de expiração no futuro.

  • A chave de conta usada para criar as SAS é regenerada. Regenerar uma chave de conta faz com que todos os componentes do aplicativo que usam essa chave não sejam autorizados até que sejam atualizados para usar a outra chave de conta válida ou a chave da conta recém-regenerada. Regenerar a chave da conta é a única maneira de revogar imediatamente uma SAS ad hoc.

Importante

Um URI de assinatura de acesso compartilhado está associado à chave da conta usada para criar a assinatura e a política de acesso armazenado associada, se aplicável. Se nenhuma política de acesso armazenado for especificada, a única maneira de revogar uma assinatura de acesso compartilhado é alterar a chave da conta.

Como prática recomendada, recomendamos que você use uma política de acesso armazenado com uma SAS de serviço. Se você optar por não usar uma política de acesso armazenado, mantenha o período durante o qual a SAS ad hoc é curta. Para obter mais informações sobre como associar uma SAS de serviço a uma política de acesso armazenada, consulte Definir uma política de acesso armazenado.

Exemplo de SAS de serviço

O exemplo a seguir mostra um URI SAS de serviço que fornece permissões de leitura e gravação para um blob.

https://myaccount.blob.core.windows.net/sascontainer/sasblob.txt?sv=2019-02-02&st=2019-04-29T22%3A18%3A26Z&se=2019-04-30T02%3A23%3A26Z&sr=b&sp=rw&sip=168.1.5.60-168.1.5.70&spr=https&sig=Z%2FRHIX5Xcg0Mq2rqI3OlWTjEg2tYkboXr1P9ZUXDtkk%3D

Cada parte do URI é descrita na tabela a seguir:

Nome Parte SAS Descrição
URI de recurso https://myaccount.blob.core.windows.net/sascontainer/sasblob.txt O endereço do blob. É altamente recomendável que você use HTTPS.
Versão do Armazenamento do Azure sv=2019-02-02 Para o Armazenamento do Azure versão 2012-02-12 e posterior, esse parâmetro indica a versão a ser usada.
Hora de início st=2019-04-29T22%3A18%3A26Z Especificado no horário UTC. Se você quiser que a SAS seja imediatamente válida, omita a hora de início.
Hora de expiração se=2019-04-30T02%3A23%3A26Z Especificado no horário UTC.
Recurso sr=b O recurso é um blob.
Permissões sp=rw As permissões concedidas pelas SAS incluem Ler (r) e Gravar (w).
Intervalo IP sip=168.1.5.60-168.1.5.70 O intervalo de endereços IP do qual uma solicitação será aceita.
Protocolo spr=https Somente solicitações que usam HTTPS são permitidas.
Assinatura sig=Z%2FRHIX5Xcg0Mq2rqI3OlWTjEg2tYkboXr1P9ZUXDtkk%3D Usada para autorizar o acesso ao blob. A assinatura é um HMAC que é computado em uma cadeia de caracteres para assinar e uma chave usando o algoritmo SHA256 e, em seguida, codificado usando a codificação Base64.

Confira também