Create a service SAS (Criar uma SAS de serviço)

  • Artigo

Uma assinatura de acesso partilhado de serviço (SAS) delega o 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 Ficheiros do Azure. O URI para uma SAS ao nível do serviço consiste no URI para o recurso para o qual a SAS irá delegar o acesso, seguido do token de SAS.

O token de SAS é a cadeia de consulta que inclui todas as informações necessárias para autorizar um pedido. O token especifica o recurso a que um cliente pode aceder, 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 ou intervalo de endereços suportado a partir do qual os pedidos podem ter origem, o protocolo suportado com o qual um pedido pode ser feito ou um identificador de política de acesso opcional associado ao pedido.

Por fim, cada token de SAS inclui uma assinatura.

Atenção

As assinaturas de acesso partilhado são chaves que concedem permissões aos recursos de armazenamento e deve protegê-las tal como protegeria uma chave de conta. É importante proteger uma SAS contra utilização maliciosa ou não intencional. Utilize a discrição na distribuição de uma SAS e tenha um plano para revogar uma SAS comprometida. As operações que utilizam assinaturas de acesso partilhado só devem ser executadas através de uma ligação HTTPS e os URIs de SAS devem ser distribuídos apenas numa ligação segura, como HTTPS.

Autorizar uma SAS de serviço

Pode proteger uma SAS de conta com uma chave de conta de armazenamento. Quando cria uma SAS de conta, a aplicação cliente tem de possuir a chave de conta.

Para utilizar Microsoft Entra credenciais para proteger uma SAS para um contentor ou blob, crie uma SAS de delegação de utilizador.

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

Uma SAS de serviço suporta o âmbito do diretório (sr=d) quando a versão de autorização (sv) é 2020-02-10 ou posterior e um espaço de nomes hierárquico está ativado. A semântica para o âmbito do diretório (sr=d) é semelhante à do âmbito do contentor (sr=c), exceto que o acesso está restrito a um diretório e a quaisquer ficheiros e subdiretórios no mesmo. Quando sr=d for especificado, o sdd parâmetro de consulta também é necessário.

O formato de cadeia a sinal para a versão de autorização 2020-02-10 permanece inalterado.

Construir uma SAS de serviço

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

Diagrama dos elementos de parâmetros de um URL de assinatura de acesso partilhado.

As secções seguintes descrevem como especificar os parâmetros que compõem o token de SAS do serviço.

Especificar o signedVersion campo

O signedVersion campo (sv) contém a versão de serviço da assinatura de acesso partilhado. Este valor especifica a versão da autorização de Chave Partilhada utilizada por esta assinatura de acesso partilhado (no signature campo). O valor também especifica a versão do serviço para pedidos efetuados com esta assinatura de acesso partilhado.

Para obter informações sobre que versão é utilizada quando executa pedidos através de uma assinatura de acesso partilhado, veja Controlo de versões dos serviços de Armazenamento do Azure.

Para obter informações sobre como este parâmetro afeta a autorização dos pedidos feitos com uma assinatura de acesso partilhado, veja Delegar acesso com uma assinatura de acesso partilhado.

Nome do campo Parâmetro de consulta Description
signedVersion sv Obrigatório. Suportado na versão 2012-02-12 e posterior. A versão do serviço de armazenamento a utilizar para autorizar e processar pedidos efetuados com esta assinatura de acesso partilhado. Para obter mais informações, veja Controlo de versões dos serviços de Armazenamento do Azure.

Determinar a versão de um pedido SAS legado

Em cenários legados em que signedVersion não é utilizado, o Armazenamento de Blobs aplica regras para determinar a versão. Para obter mais informações sobre estas regras, veja Controlo de versões dos serviços de Armazenamento do Azure.

Importante

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

Especifique o recurso assinado (apenas o Armazenamento de Blobs)

O campo necessário signedResource (sr) especifica os recursos que estão acessíveis através da assinatura de acesso partilhado. A tabela seguinte descreve como fazer referência a um recurso de blob ou contentor no token de SAS.

Recurso Valor do parâmetro Versões suportadas Description
Blob b Todos 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 do blob, mas não ao blob base.
Contentor c Todos Concede acesso ao conteúdo e metadados de qualquer blob no contentor e à lista de blobs no contentor.
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, numa conta de armazenamento com um espaço de nomes hierárquico ativado. Se for especificado um diretório para o signedResource campo, o signedDirectoryDepth parâmetro (sdd) também é necessário. Um diretório é sempre aninhado num contentor.

Especifique o recurso assinado (Ficheiros do Azure)

A SAS é suportada para Ficheiros do Azure versão 2015-02-21 e posterior.

O signedResource campo especifica os recursos que estão acessíveis através da assinatura de acesso partilhado. A tabela seguinte descreve como fazer referência a um ficheiro ou a um recurso de partilha no URI.

Nome do campo Parâmetro de consulta Description
signedResource sr Obrigatório.

Especifique f se o recurso partilhado é um ficheiro. Ao fazê-lo, concede acesso aos conteúdos e metadados do ficheiro.

Especifique s se o recurso partilhado é uma partilha. Ao fazê-lo, concede acesso ao conteúdo e metadados de qualquer ficheiro na partilha e à lista de diretórios e ficheiros na partilha.

Especificar parâmetros de consulta para substituir cabeçalhos de resposta (Apenas armazenamento de blobs e Ficheiros do Azure)

Para definir valores para que determinados cabeçalhos de resposta sejam devolvidos quando a assinatura de acesso partilhado é utilizada num pedido, pode especificar cabeçalhos de resposta em parâmetros de consulta. Esta funcionalidade é suportada a partir da versão 2013-08-15 para Armazenamento de Blobs e versão 2015-02-21 para Ficheiros do Azure. As assinaturas de acesso partilhado que utilizam esta funcionalidade têm de incluir o sv parâmetro definido como 2013-08-15 ou posterior para o Armazenamento de Blobs ou para 2015-02-21 ou posterior para Ficheiros do Azure.

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

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

Por exemplo, se especificar o rsct=binary parâmetro de consulta numa assinatura de acesso partilhado criada com a versão 2013-08-15 ou posterior, o Content-Type cabeçalho de resposta está definido como binary. Este valor substitui o Content-Type valor do cabeçalho armazenado para o blob para um pedido que utiliza apenas esta assinatura de acesso partilhado.

Se criar uma assinatura de acesso partilhado que especifica cabeçalhos de resposta como parâmetros de consulta, tem de incluí-los na cadeia de carateres a assinar que é utilizada para construir a cadeia de assinatura. Para obter mais informações, consulte a secção "Construir a cadeia de assinatura" mais à frente neste artigo. Para obter exemplos adicionais, veja Exemplos de SAS de Serviço.

Especifique o nome da tabela (apenas Armazenamento de Tabelas)

O tableName campo especifica o nome da tabela a partilhar.

Nome do campo Parâmetro de consulta Description
tableName tn Obrigatório. O nome da tabela a partilhar.

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 partilhado é válida e as permissões a conceder ao utilizador. As partes do URI que compõem a política de acesso estão descritas na seguinte tabela:

Nome do campo Parâmetro de consulta Descrição
signedStart st Opcional. A hora em que a assinatura de acesso partilhado se torna válida, expressa num dos formatos ISO 8601 UTC aceites. Se este parâmetro for omitido, a hora UTC atual é utilizada 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 seja utilizada uma política de contentor. Para obter mais informações sobre os formatos UTC aceites, veja Formatar valores de data/hora.
signedExpiry se Obrigatório. A hora em que a assinatura de acesso partilhado se torna inválida, expressa num dos formatos ISO 8601 UTC aceites. Tem de omitir este campo se tiver sido especificado numa política de acesso armazenada associada. Para obter mais informações sobre os formatos UTC aceites, veja Formatar valores de data/hora.
signedPermissions1 sp Obrigatório. As permissões associadas à assinatura de acesso partilhado. O utilizador está restrito a operações permitidas pelas permissões. Tem de omitir este campo se tiver sido especificado numa política de acesso armazenada associada.
startPk2

startRk2		 spk

srk		 Apenas Armazenamento de Tabelas.

Opcional, mas startPk tem de acompanhar startRk. As chaves mínimas de partição e linha que estão acessíveis com esta assinatura de acesso partilhado. Os valores-chave são inclusivos. Se forem omitidos, não existe um limite inferior nas entidades de tabela que possam ser acedidas.
endPk2

endRk2		 epk

erk		 Apenas Armazenamento de Tabelas.

Opcional, mas endPk tem de acompanhar endRk. As chaves de partição e linha máximas que estão acessíveis com esta assinatura de acesso partilhado. Os valores-chave são inclusivos. Se forem omitidos, não existe um limite superior nas entidades de tabela que possam ser acedidas.

1 O signedPermissions campo é necessário no URI, a menos que seja especificado como parte de uma política de acesso armazenada.
2 Os startPkcampos , startRk, endPke só endRk podem ser especificados nos recursos de Armazenamento de Tabelas.

Especificar permissões

As permissões especificadas para o signedPermissions campo (sp) no token de SAS indicam as operações que um cliente pode realizar no recurso.

Pode combinar permissões para permitir que um cliente efetue várias operações com a mesma SAS. Quando constrói a SAS, tem de incluir permissões pela seguinte ordem:

racwdxltmeop

Exemplos de definições de permissões válidas para um contentor incluem rw, , rlrd, , wde wlrl. Exemplos de definições inválidas incluem wr, dr, e lrdw. Não pode especificar uma designação de permissão mais do que uma vez.

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

  • Não é possível criar, eliminar ou listar contentores, filas e tabelas.
  • Os metadados de contentor e as propriedades não podem ser lidos ou escritos.
  • As filas não podem ser limpas e os metadados não podem ser escritos.
  • Os contentores não podem ser arrendados.

Para construir uma SAS que conceda acesso a estas operações, utilize uma SAS de conta. Para obter mais informações, veja Criar uma SAS de conta.

Importante

As assinaturas de acesso partilhado são chaves que concedem permissões aos recursos de armazenamento e deve protegê-las tal como protegeria uma chave de conta. Execute operações que utilizem assinaturas de acesso partilhado apenas através de uma ligação HTTPS e distribua URIs de assinatura de acesso partilhado apenas numa ligação segura, como HTTPS.

As permissões suportadas para cada tipo de recurso são descritas nas secções seguintes.

Permissões para um diretório, contentor ou blob

As permissões suportadas para cada tipo de recurso estão descritas na seguinte tabela:

Permissão Símbolo de URI Recurso Suporte da versão Operações permitidas
Leitura r Contentor
Diretório
Blob		 Todos Leia o conteúdo, a lista de bloqueios, as propriedades e os metadados de qualquer blob no contentor ou diretório. Utilize um blob como a origem de uma operação de cópia.
Adicionar um Contentor
Diretório
Blob		 Todos Adicione um bloco a um blob de acréscimo.
Criar c Contentor
Diretório
Blob		 Todos Escreva um novo blob, copie um blob ou copie um blob para um novo blob.
Escrita w Contentor
Diretório
Blob		 Todos Criar ou escrever conteúdo, propriedades, metadados ou lista de bloqueios. Instantâneo ou arrenda o blob. Redimensione o blob (apenas blob de páginas). Utilize o blob como destino de uma operação de cópia.
Eliminar d Contentor
Diretório
Blob		 Todos Eliminar um blob. Para a versão 2017-07-29 e posterior, a permissão Eliminar também permite quebrar uma concessão num blob. Para obter mais informações, veja a operação Lease Blob (Concessão de Blobs ).
Eliminar versão x Contentor
Blob		 2019-12-12 e posterior Eliminar uma versão de blob.
Eliminar de forma permanente y Blob 2020-02-10 e posterior Elimine permanentemente um instantâneo de blob ou uma versão.
Lista l Contentor
Diretório		 Todos Listar blobs de forma não recursiva.
Etiquetas t Blob 2019-12-12 e posterior Leia ou escreva as etiquetas num blob.
Localizar f Contentor 2019-12-12 e posterior Localizar blobs com etiquetas de índice.
Mover m Contentor
Diretório
Blob		 2020-02-10 e posterior Mova um blob ou um diretório e os respetivos conteúdos para uma nova localização. Opcionalmente, esta operação pode ser restrita ao proprietário do blob, diretório ou diretório principal subordinado se o saoid parâmetro estiver incluído no token de SAS e o sticky bit estiver definido no diretório principal.
Executar e Contentor
Diretório
Blob		 2020-02-10 e posterior Obtenha as propriedades do sistema e, se o espaço de nomes hierárquico estiver ativado para a conta de armazenamento, obtenha a ACL POSIX de um blob. Se o espaço de nomes hierárquico estiver ativado e o autor da chamada for o proprietário de um blob, esta permissão concede a capacidade de definir o grupo proprietário, as permissões POSIX e a ACL POSIX do blob. não permite que o autor da chamada leia metadados definidos pelo utilizador.
Propriedade o Contentor
Diretório
Blob		 2020-02-10 e posterior Quando o espaço de nomes hierárquico está ativado, esta permissão permite que o autor da chamada defina o proprietário ou o grupo proprietário, ou aja como proprietário ao mudar o nome ou eliminar um diretório ou blob num diretório com o conjunto de bits autocolantes.
Permissões p Contentor
Diretório
Blob		 2020-02-10 e posterior Quando o espaço de nomes hierárquico está ativado, esta permissão permite que o autor da chamada defina permissões e ACLs POSIX em diretórios e blobs.
Definir Política de Imutabilidade i Contentor
Blob		 2020-06-12 e posterior Defina ou elimine a política de imutabilidade ou a retenção legal num blob.

Permissões para um ficheiro

Permissão Símbolo de URI Operações permitidas
Leitura r Leia os conteúdos, propriedades e metadados. Utilize o ficheiro como a origem de uma operação de cópia.
Criar c Crie um novo ficheiro ou copie um ficheiro para um novo ficheiro.
Escrita w Criar ou escrever conteúdos, propriedades e metadados. Redimensione o ficheiro. Utilize o ficheiro como destino de uma operação de cópia.
Eliminar d Elimine o ficheiro.

Permissões para uma partilha

Permissão Símbolo de URI Operações permitidas
Leitura r Leia os conteúdos, propriedades ou metadados de qualquer ficheiro na partilha. Utilize qualquer ficheiro na partilha como a origem de uma operação de cópia.
Criar c Crie um novo ficheiro na partilha ou copie um ficheiro para um novo ficheiro na partilha.
Escrita w Para qualquer ficheiro na partilha, crie ou escreva conteúdo, propriedades ou metadados. Redimensione o ficheiro. Utilize o ficheiro como destino de uma operação de cópia. Nota: não pode conceder permissões para ler ou escrever propriedades ou metadados de partilha através de uma SAS de serviço. Em alternativa, utilize uma SAS de conta.
Eliminar d Elimine qualquer ficheiro na partilha. Nota: não pode conceder permissões para eliminar uma partilha com uma SAS de serviço. Em alternativa, utilize uma SAS de conta.
Lista l Listar ficheiros e diretórios na partilha.

Permissões para uma fila

Permissão Símbolo de URI Operações permitidas
Leitura r Leia metadados e propriedades, incluindo a contagem de mensagens. Pré-visualizar em mensagens.
Adicionar um Adicione mensagens à fila.
Atualizar u Atualizar mensagens na fila. Nota: utilize a permissão Processo com a Atualização para obter primeiro a mensagem que pretende atualizar.
Processo p Obtenha e elimine mensagens da fila.

Permissões para uma tabela

Permissão Símbolo de URI Operações permitidas
Consulta r Obtenha entidades e entidades de consulta.
Adicionar um Adicionar entidades. Nota: as permissões Adicionar e Atualizar são necessárias para operações de upsert.
Atualizar u Atualizar entidades. Nota: as permissões Adicionar e Atualizar são necessárias para operações de upsert.
Eliminar d Eliminar 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 a partir dos quais aceitar pedidos. Se o endereço IP a partir do qual o pedido é originado não corresponder ao endereço IP ou intervalo de endereços especificado no token de SAS, o pedido não está autorizado. Só são suportados endereços IPv4.

Quando estiver a especificar um intervalo de endereços IP, tenha em atenção que o intervalo é inclusivo. Por exemplo, especificar sip=168.1.5.65 ou sip=168.1.5.60-168.1.5.70 no SAS restringe o pedido a esses endereços IP.

A tabela seguinte descreve se deve incluir o signedIp campo num token de SAS para um cenário especificado, com base no ambiente de cliente e na localização da conta de armazenamento.

Ambiente de cliente Localização 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. Os pedidos efetuados a partir da mesma região que utilizam uma SAS com um endereço IP de saída especificado falharão.

Em vez disso, utilize uma rede virtual do Azure para gerir restrições de segurança de rede. Os pedidos para o Armazenamento do Azure a partir da mesma região ocorrem sempre através de um endereço IP privado. Para obter mais informações, veja Configurar firewalls e redes virtuais do Armazenamento do Microsoft Azure.
Cliente em execução no Azure Numa 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. Um pedido feito com a SAS tem de ter origem no endereço IP especificado ou no intervalo de endereços.
Cliente a executar no local ou num ambiente de cloud 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. Um pedido feito com a SAS tem de ter origem no endereço IP especificado ou no intervalo de endereços.

Se o pedido 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 um pedido feito com a SAS. Os valores possíveis são apenas HTTPS e HTTP (https,http) ou HTTPS (https). O valor predefinido é https,http. Tenha em atenção que HTTP apenas não é um valor permitido.

Especificar intervalos de acesso a tabelas

Os startPkcampos , startRk, endPke endRk definem um intervalo de entidades de tabela que estão associadas a uma assinatura de acesso partilhado. As consultas de tabela devolvem apenas os resultados dentro do intervalo e as tentativas de utilizar a assinatura de acesso partilhado para adicionar, atualizar ou eliminar entidades fora deste intervalo falharão.

Se startPk for igual endPka , a assinatura de acesso partilhado autoriza o acesso a entidades em apenas uma partição na tabela.

Se startPk for igual e startRk igual endPkendRka , a assinatura de acesso partilhado só pode aceder a uma entidade numa partição.

Para compreender como estes campos restringem o acesso a entidades numa tabela, veja a seguinte tabela:

Campos presentes Âmbito 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 espaço de nomes hierárquico está ativado e o signedResource campo especifica um diretório (sr=d), também tem de especificar o signedDirectoryDepth campo (sdd) para indicar o número de subdiretórios no diretório de raiz. O valor do sdd campo tem de ser um número inteiro não negativo.

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

Este campo é suportado com a versão 2020-02-10 ou posterior.

Especificar o identificador assinado

Quando especifica o signedIdentifier campo no URI, relaciona a assinatura de acesso partilhado especificada a uma política de acesso armazenado correspondente. Uma política de acesso armazenado fornece uma medida adicional de controlo sobre uma ou mais assinaturas de acesso partilhado, incluindo a capacidade de revogar a assinatura, se necessário. Cada contentor, fila, tabela ou partilha pode ter até cinco políticas de acesso armazenadas.

A tabela seguinte descreve como fazer referência a um identificador assinado no URI:

Nome do campo Parâmetro de consulta Descrição
signedIdentifier si Opcional. Um valor exclusivo de até 64 carateres que está correlacionado com uma política de acesso especificada para o contentor, fila ou tabela.

Uma política de acesso armazenado inclui um identificador assinado, um valor de até 64 carateres que é exclusivo dentro do recurso. Pode especificar o valor deste identificador assinado para o signedidentifier campo no URI para a assinatura de acesso partilhado. Quando especifica um identificador assinado no URI, associa a assinatura à política de acesso armazenado. Para estabelecer uma política de acesso ao nível do contentor com a API REST, veja Delegar o acesso com uma assinatura de acesso partilhado.

Especificar o âmbito de encriptação

Ao utilizar o signedEncryptionScope campo no URI, pode especificar o âmbito de encriptação que a aplicação cliente pode utilizar. Impõe a encriptação do lado do servidor com o âmbito de encriptação especificado quando carrega blobs (PUT) com o token de SAS. O GET e o HEAD não serão restringidos e executados como anteriormente.

A tabela seguinte descreve como fazer referência a um âmbito de encriptação assinado no URI:

Nome do campo Parâmetro de consulta Descrição
signedEncryptionScope ses Opcional. Indica o âmbito de encriptação a utilizar para encriptar o conteúdo do pedido.

Este campo é suportado com a versão 2020-12-06 ou posterior. Se adicionar o ses antes da versão suportada, o serviço devolve o código de resposta de erro 403 (Proibido).

Se definir o âmbito de encriptação predefinido para o sistema de contentores ou ficheiros, o ses parâmetro de consulta respeita a política de encriptação de contentor. Se existir um erro de correspondência 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 como true, o serviço devolve o código de resposta de erro 403 (Proibido).

Quando fornece o x-ms-encryption-scope cabeçalho e o ses parâmetro de consulta no pedido PUT, o serviço devolve o código de resposta de erro 400 (Pedido Incorreto) se existir um erro de correspondência.

Especificar a assinatura

Utilize a parte de assinatura do URI para autorizar o pedido efetuado com a assinatura de acesso partilhado. O Armazenamento do Azure utiliza um esquema de autorização de Chave Partilhada para autorizar uma SAS de serviço.

A tabela seguinte descreve como especificar a assinatura no URI:

Nome do campo Parâmetro de consulta Descrição
signature sig A cadeia de carateres a assinar é uma cadeia exclusiva que é construída a partir dos campos e que tem de ser verificada para autorizar o pedido. A assinatura é um código de autenticação de mensagens baseado em hash (HMAC) que calcula através da cadeia para assinar e da chave com o algoritmo SHA256 e, em seguida, codifica através da codificação Base64.

Construir a cadeia de assinatura

Para construir a cadeia de assinatura de uma assinatura de acesso partilhado, crie primeiro a cadeia de carateres para assinar a partir dos campos que compõem o pedido, codifica a cadeia como UTF-8 e, em seguida, calcule a assinatura com o algoritmo HMAC-SHA256. Os campos incluídos na cadeia para assinar têm de ser descodificados por URL.

Versão 2020-12-06 e posterior

A versão 2020-12-06 adiciona suporte para o campo de âmbito de encriptação assinado. Para construir a cadeia de carateres para assinar para os recursos do Armazenamento de Blobs, utilize 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 os campos de tempo de instantâneo de blobs assinados. Estes campos têm de ser incluídos na cadeia a assinar. Para construir a cadeia de carateres para assinar para os recursos do Armazenamento de Blobs, utilize 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 o IP assinado e campos de protocolo assinados. Estes campos têm de ser incluídos na cadeia a assinar. Para construir a cadeia de carateres para assinar para o Armazenamento de Blobs ou Ficheiros do Azure recursos, utilize 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 carateres para assinar para recursos de Armazenamento de Tabelas, utilize 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 carateres para assinar para os recursos do Armazenamento de Filas, utilize o seguinte formato:

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

Para construir a cadeia para assinar para o Armazenamento de Blobs ou Ficheiros do Azure recursos com a versão 2013-08-15 a 2015-02-21, utilize o seguinte formato. Para Ficheiros do Azure, a SAS é suportada 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 cadeia de carateres para assinar para uma tabela, utilize 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 carateres para assinar para uma fila, utilize 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 carateres para assinar os recursos do Armazenamento de Blobs para a versão 2012-02-12, utilize 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 para assinar para recursos do Armazenamento de Blobs para versões anteriores a 2012-02-12, utilize o seguinte formato:

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

Quando estiver a construir a cadeia a assinar, tenha em atenção o seguinte:

  • Se um campo for opcional e não for fornecido como parte do pedido, especifique uma cadeia vazia para esse campo. Certifique-se de que inclui o caráter newline (\n) após a cadeia vazia.

  • A cadeia de carateres para assinar para uma tabela tem de incluir os parâmetros adicionais, mesmo que estejam em cadeias vazias.

  • A signedpermission parte da cadeia tem de incluir as designações de permissão numa ordem fixa específica para cada tipo de recurso. Qualquer combinação destas permissões é aceitável, mas a ordem das cartas de permissão tem de corresponder à ordem na tabela seguinte.

    Tipo de recurso Ordem das permissões
    Blob racwd
    Contentor racwdl
    Fila raup
    Ficheiro rcwd
    Partilhar rcwdl
    Tabela raud

    Por exemplo, exemplos de definições de permissões válidas para um contentor incluem rw, , rd, rl, wd, wle rl. Exemplos de definições inválidas incluem wr, dr, e lrdw. Não é permitida a especificação de uma designação de permissão mais do que uma vez.

  • Forneça um valor para a signedIdentifier parte da cadeia se estiver a associar o pedido a uma política de acesso armazenada.

  • Uma assinatura de acesso partilhado que especifica uma versão do serviço de armazenamento anterior a 2012-02-12 só pode partilhar um blob ou contentor e tem de omitir signedVersion e o caráter newline antes dele.

  • A canonicalizedResource parte da cadeia é um caminho canónico para o recurso assinado. Tem de incluir o nome do serviço (Armazenamento de Blobs, Armazenamento de Tabelas, Armazenamento de Filas ou Ficheiros do Azure) para a versão 2015-02-21 ou posterior, o nome da conta de armazenamento e o nome do recurso e tem de ser descodificado por URL. Os nomes dos blobs têm de incluir o contentor do blob. Os nomes das tabelas têm de estar em minúsculas.

A cadeia de recursos canonizada para um contentor, fila, tabela ou partilha de ficheiros tem de omitir a barra à direita (/) para uma SAS que forneça acesso a esse objeto.

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

Contentores

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"

Partilhas de Ficheiros

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

Ficheiros

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, certifique-se de que o nome da tabela está em minúsculas no formato canonizado.

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"

Duração e revogação de uma assinatura de acesso partilhado

As assinaturas de acesso partilhado concedem aos utilizadores direitos de acesso aos recursos da conta de armazenamento. Quando estiver a planear utilizar uma SAS, pense na duração da SAS e se a sua aplicação poderá ter de revogar direitos de acesso em determinadas circunstâncias.

SAS ad hoc versus política de acesso armazenada

Uma SAS de serviço pode assumir uma de duas formas:

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

    Pode gerir a duração de uma SAS ad hoc com o signedExpiry campo . Se quiser continuar a conceder acesso de cliente ao recurso após a expiração, tem de emitir uma nova assinatura. Recomendamos que mantenha a duração de uma assinatura de acesso partilhado curta. Antes da versão 2012-02-12, uma assinatura de acesso partilhado não associada a uma política de acesso armazenada não podia ter um período ativo que excedesse uma hora.

  • SAS com política de acesso armazenada: uma política de acesso armazenada é definida num contentor de recursos, que pode ser um contentor de blobs, tabela, fila ou partilha de ficheiros. Pode utilizar a política de acesso armazenada para gerir restrições para uma ou mais assinaturas de acesso partilhado. Quando 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 signedIdentifier campo no URI. Uma política de acesso armazenada fornece uma medida adicional de controlo sobre uma ou mais assinaturas de acesso partilhado, incluindo a capacidade de revogar a assinatura, se necessário.

Revogar uma SAS

Uma vez que um URI de SAS é um URL, qualquer pessoa que obtenha a SAS pode utilizá-lo, independentemente de quem o criou originalmente. Se uma SAS for publicada publicamente, pode ser utilizada por qualquer pessoa no mundo. Uma SAS concede acesso a recursos a qualquer pessoa que a possua até que uma das quatro coisas aconteça:

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

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

    O tempo de expiração pode ser atingido porque o intervalo decorre ou porque modificou a política de acesso armazenada para ter um tempo de expiração no passado, que é uma forma de revogar a SAS.

  • A política de acesso armazenada referenciada pela SAS é eliminada, 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 partilhado, o cliente não poderá aceder ao recurso indicado pelo URI.

    Se recriar a política de acesso armazenada com exatamente o mesmo nome que a política eliminada, todos os tokens SAS existentes serão novamente válidos, de acordo com as permissões associadas a essa política de acesso armazenada. Isto pressupõe que o tempo de expiração na SAS não passou. Se pretender revogar a SAS, certifique-se de que utiliza um nome diferente quando recriar a política de acesso com um tempo de expiração no futuro.

  • A chave de conta que foi utilizada para criar a SAS é regenerada. Regenerar uma chave de conta faz com que todos os componentes da aplicação que utilizam essa chave não autorizem até serem atualizados para utilizarem a outra chave de conta válida ou a chave de conta recém-regenerada. Regenerar a chave de conta é a única forma de revogar imediatamente uma SAS ad hoc.

Importante

Um URI de assinatura de acesso partilhado está associado à chave de conta utilizada para criar a assinatura e a política de acesso armazenada associada, se aplicável. Se não for especificada nenhuma política de acesso armazenada, a única forma de revogar uma assinatura de acesso partilhado é alterar a chave da conta.

Como melhor prática, recomendamos que utilize uma política de acesso armazenada com uma SAS de serviço. Se optar por não utilizar uma política de acesso armazenada, certifique-se de que mantém o período durante o qual a SAS ad hoc é válida. Para obter mais informações sobre como associar uma SAS de serviço a uma política de acesso armazenada, veja Definir uma política de acesso armazenada.

Exemplo de SAS de serviço

O exemplo seguinte mostra um URI de blob com um token de SAS de serviço anexado ao mesmo. O token de SAS do serviço fornece permissões de leitura e escrita para o blob.

https://myaccount.blob.core.windows.net/sascontainer/blob1.txt?sp=rw&st=2023-05-24T01:13:55Z&se=2023-05-24T09:13:55Z&sip=168.1.5.60-168.1.5.70&spr=https&sv=2022-11-02&sr=b&sig=<signature>

Cada parte do URI é descrita na tabela seguinte:

Name Parte SAS Description
URI do Recurso https://myaccount.blob.core.windows.net/sascontainer/blob1.txt O endereço do blob. Recomendamos vivamente que utilize HTTPS.
Delimitador ? O delimitador que precede a cadeia de consulta. O delimitador não faz parte do token de SAS.
Permissões sp=rw As permissões concedidas pela SAS incluem Leitura (r) e Escrita (w).
Hora de início st=2023-05-24T01:13:55Z Especificado na hora UTC. Se quiser que a SAS seja válida imediatamente, omita a hora de início.
Hora de expiração se=2023-05-24T09:13:55Z Especificado na hora UTC.
Intervalo de IP sip=168.1.5.60-168.1.5.70 O intervalo de endereços IP a partir do qual um pedido será aceite.
Protocolo spr=https Só são permitidos pedidos que utilizem HTTPS.
Versão do Armazenamento do Azure sv=2023-05-24 Para a versão 2012-02-12 do Armazenamento do Azure e posterior, este parâmetro indica a versão a utilizar.
Recurso sr=b O recurso é um blob.
Assinatura sig=<signature> Utilizado para autorizar o acesso ao blob. A assinatura é um HMAC que é calculado através de uma cadeia de carateres e chave através do algoritmo SHA256 e, em seguida, codificado através da codificação Base64.

Ver também