Criar uma SAS de serviço

  • Artigo

Importante

Para obter a segurança ideal, a Microsoft recomenda usar Microsoft Entra ID com identidades gerenciadas para autorizar solicitações contra dados de blob, fila e tabela, sempre que possível. A autorização com Microsoft Entra ID e identidades gerenciadas fornece segurança superior e facilidade de uso em relação à autorização de Chave Compartilhada. Para saber mais, confira Autorizar com Microsoft Entra ID. Para saber mais sobre identidades gerenciadas, confira O que são identidades gerenciadas para recursos do Azure.

Para recursos hospedados fora do Azure, como aplicativos locais, você pode usar identidades gerenciadas por meio do Azure Arc. Por exemplo, aplicativos em execução em servidores habilitados para Azure Arc podem usar identidades gerenciadas para se conectar aos serviços do Azure. Para saber mais, confira Autenticar em recursos do Azure com servidores habilitados para Azure Arc.

Para cenários em que as SAS (assinaturas de acesso compartilhado) são usadas, a Microsoft recomenda usar uma SAS de delegação de usuário. Uma SAS de delegação de usuário é protegida com Microsoft Entra credenciais em vez da chave da conta. Para saber mais sobre assinaturas de acesso compartilhado, consulte Create uma SAS de delegação de usuário.

Uma SAS (assinatura de acesso compartilhado) de serviço 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 Arquivos do Azure. O URI de uma SAS de nível de serviço consiste no URI do recurso para o qual a SAS delegará 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 durante o qual a assinatura é válida.

Uma SAS também pode especificar o endereço IP ou o intervalo de endereços com suporte do qual as solicitações podem se originar, 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 apenas 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 Microsoft Entra credenciais para proteger uma SAS para um contêiner ou blob, crie uma SAS de delegação de usuário.

Suporte 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) é 2020-02-10 ou posterior e um namespace hierárquico está 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 de cadeia de caracteres para assinar para a versão de autorização 2020-02-10 permanece 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 do 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 Delegar acesso 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 signedVersion que 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 se referir 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 aos metadados do blob.
Versão do blob Bv 2018-11-09 e posterior Concede acesso ao conteúdo e aos 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 aos metadados do blob instantâneo, mas não ao blob base.
Contêiner c Tudo Concede acesso ao conteúdo e aos 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 aos 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 (somente Armazenamento de Blobs e 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 a partir da versão 2013-08-15 para o Armazenamento de Blobs e a 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 2013-08-15 como 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 sã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 binarycomo . Esse valor substitui o valor de Content-Type 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 na cadeia de caracteres para sinal usada 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 armazenada associada. Para obter mais informações sobre formatos UTC aceitos, consulte Formatar valores de data/hora.
signedPermissions 1 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 armazenada associada.
startPk 2

startRk 2		 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á nenhum limite inferior nas entidades de tabela que possam ser acessadas.
endPk 2

endRk 2		 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 eles forem omitidos, não haverá nenhum limite superior nas entidades de tabela que possam ser acessadas.

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 endRk 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 incluem rw, rd, rl, wd, wle rl. Exemplos de configurações inválidas incluem wr, dr, lre dw. 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 seus metadados não podem ser gravados.
  • Os contêineres não podem ser concedidos.

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 um blob ou copie um blob para um novo blob.
Gravar w Contêiner
Diretório
Blob		 Tudo Create 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 Excluir 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 s Blob 2020-02-10 e posterior Exclua permanentemente um instantâneo ou versão de blob.
Lista l Contêiner
Diretório		 Tudo Listar blobs de forma não recursiva.
Marcações t Blob 2019-12-12 e posterior Ler ou gravar 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. Opcionalmente, essa operação pode ser restrita ao proprietário do diretório pai, diretório ou blob filho se o saoid parâmetro estiver incluído no token SAS e o bit autoadesiva 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 proprietário ao renomear ou excluir um diretório ou blob dentro de um diretório que tenha o bit autoadesiva definido.
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 Create um novo arquivo ou copie um arquivo para um novo arquivo.
Gravar w Create 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 Create 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 Processar com Update para que você possa primeiro receber a mensagem que deseja atualizar.
Processar 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. Há suporte somente para endereços IPv4.

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 nesse 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 nesse 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 nesse 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 , startRk, endPke endRk 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 endPka , a assinatura de acesso compartilhado autorizará o acesso a entidades em apenas uma partição na tabela.

Se startPk for igual endPk a e startRk igual endRka , 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 em 1. O diretório https://{account}.blob.core.windows.net/{container}/d1/d2 tem uma profundidade de 2.

Esse campo tem suporte na 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 armazenada 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 armazenada 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, você associa 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 Delegar acesso 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 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 na versão 2020-12-06 ou posterior. Se você adicionar o ses antes da versão 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 ses parâmetro de 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 truecomo , 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 para assinar a partir dos campos que compõem a solicitação, codifique a cadeia de caracteres como UTF-8 e, em seguida, calcule 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 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 o blob assinado instantâneo campos de tempo. 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 ip assinado e protocolo assinado. Esses campos devem ser incluídos na cadeia de caracteres para assinar. Para construir a cadeia de caracteres a assinar para o Armazenamento de Blobs ou Arquivos do Azure recursos, 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 a 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 a assinar para 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 12/02/2012

Para construir a cadeia de caracteres a assinar para 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 incluem rw, rd, rl, wd, wle rl. Exemplos de configurações inválidas incluem wr, dr, lre dw. Especificar uma designação de permissão mais de uma vez não é permitido.

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

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 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 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, o tempo 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 obtenha a SAS pode usá-la, independentemente de quem a 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 armazenada referenciada pela SAS será atingido, se uma política de acesso armazenada 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 armazenada 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 falhem em autorizar até que sejam atualizados para usar a outra chave de conta válida ou a chave de 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 de 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 armazenada com uma SAS de serviço. Se você optar por não usar uma política de acesso armazenada, 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 de blob com um token SAS de serviço acrescentado a ele. O token SAS de serviço fornece permissões de leitura e gravação 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 a seguir:

Nome Parte SAS Descrição
URI de recurso https://myaccount.blob.core.windows.net/sascontainer/blob1.txt O endereço do blob. É altamente recomendável que você use HTTPS.
Delimitador ? O delimitador que precede a cadeia de caracteres de consulta. O delimitador não faz parte do token SAS.
Permissões sp=rw As permissões concedidas pelas SAS incluem Ler (r) e Gravar (w).
Hora de início st=2023-05-24T01:13:55Z 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=2023-05-24T09:13:55Z Especificado no horário UTC.
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.
Versão do Armazenamento do Azure sv=2023-05-24 No Armazenamento do Azure da versão 12-02-2012 e posterior, este parâmetro indica a versão a ser usada.
Recurso sr=b O recurso é um blob.
Assinatura sig=<signature> Usada para autorizar o acesso ao blob. A assinatura é um HMAC calculado em uma cadeia de caracteres para assinar e uma chave usando o algoritmo SHA256 e codificado usando a codificação Base64.

Confira também