Criar uma SAS de delegação de usuário
Importante
Para obter a segurança ideal, a Microsoft recomenda usar a ID do Microsoft Entra com identidades gerenciadas para autorizar solicitações contra dados de blob, fila e tabela, sempre que possível. A autorização com a ID do Microsoft Entra e identidades gerenciadas fornece segurança superior e facilidade de uso sobre a autorização de Chave Compartilhada. Para saber mais, consulte Autorizar com o Microsoft Entra ID. Para saber mais sobre identidades gerenciadas, consulte 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, consulte Autenticar em recursos do Azure com servidores habilitados para Azure Arc.
Você pode proteger um token SAS (assinatura de acesso compartilhado) para acesso a um contêiner, diretório ou blob usando credenciais do Microsoft Entra ou uma chave de conta. Uma SAS protegida com as credenciais do Microsoft Entra é chamada de SAS delegação de usuário. Como prática recomendada de segurança, recomendamos que você use as credenciais do Microsoft Entra quando possível, em vez da chave da conta, que pode ser comprometida com mais facilidade. Quando o design do aplicativo exigir assinaturas de acesso compartilhado, use as credenciais do Microsoft Entra para criar uma SAS de delegação de usuário para ajudar a garantir uma melhor segurança.
Cada SAS é assinada com uma chave. Para criar uma SAS de delegação de usuário, primeiro você deve solicitar uma chave de delegação de usuário , que você usa para assinar a SAS. A chave de delegação do usuário é análoga à chave de conta usada para assinar uma SAS de serviço ou uma SAS de conta, exceto que ela depende de suas credenciais do Microsoft Entra. Para solicitar a chave de delegação do usuário, chame a operação Obter Chave de Delegação de Usuário. Em seguida, você pode usar a chave de delegação do usuário para criar a SAS.
Há suporte para uma SAS de delegação de usuário para o Armazenamento de Blobs do Azure e o Azure Data Lake Storage. As políticas de acesso armazenado não têm suporte para uma SAS de delegação de usuário.
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 uma SAS contra uso mal-intencionado ou não intencional. Use a discrição na distribuição de uma SAS e tenha um plano em vigor para revogar uma SAS comprometida. As operações que usam assinaturas de acesso compartilhado devem ser executadas somente em uma conexão HTTPS e as URIs de assinatura de acesso compartilhado só devem ser distribuídas em uma conexão segura, como HTTPS.
Para obter informações sobre como usar sua chave de conta para proteger uma SAS, consulte Criar um serviço sas e criar uma conta SAS.
Suporte à SAS de delegação de usuário para acesso com escopo de diretório
Uma SAS de delegação de usuário 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 HNS (namespace hierárquico) estiver habilitado. A semântica para escopo de diretório (sr=d) é semelhante ao escopo do 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 parâmetro de consulta sdd também é necessário.
O formato cadeia de caracteres para assinar para a versão de autorização 2020-02-10 está inalterado.
Suporte à SAS de delegação de usuário para uma OID de usuário
A SAS de delegação de usuário dá suporte a um OID (identificador de objeto de usuário) opcional que é transportado no parâmetro saoid ou suoid quando a versão de autorização (sv) for 2020-02-10 ou posterior. Os parâmetros saoid e suoid correspondem à entidade de segurança do usuário final que está usando a SAS e fornecem um modelo de autorização aprimorado para cargas de trabalho de cluster de vários usuários, como Hadoop e Spark.
Os tokens SAS podem ser restritos a uma operação específica do sistema de arquivos e ao usuário, que fornece um token de acesso menos vulnerável que é mais seguro de distribuir em um cluster de vários usuários. Um caso de uso para esses recursos é a integração do driver ABFS do Hadoop com o Apache Ranger.
Para saber mais sobre os parâmetros opcionais saoid e suoid, consulte Especificar uma ID de objeto de usuário assinada.
Autorizar uma SAS de delegação de usuário
Quando um cliente acessa um recurso de Armazenamento de Blobs com uma SAS de delegação de usuário, a solicitação para o Armazenamento do Azure é autorizada com as credenciais do Microsoft Entra que foram usadas para criar a SAS. O acesso do cliente ao recurso é determinado pelas seguintes permissões:
- As permissões de RBAC (controle de acesso baseado em função) que são concedidas à entidade de segurança do Microsoft Entra que solicitou a chave de delegação do usuário.
- As permissões de ACL (lista de controle de acesso) POSIX concedidas à entidade de segurança que solicitou a chave de delegação do usuário. Essa verificação adicional só acontece quando as permissões RBAC não podem conceder acesso e somente quando o namespace hierárquico está habilitado na conta de armazenamento.
- As permissões que são explicitamente concedidas no token SAS.
Essa abordagem fornece um nível adicional de segurança e ajuda você a evitar ter que armazenar sua chave de acesso de conta com o código do aplicativo. Por esses motivos, criar uma SAS usando as credenciais do Microsoft Entra é uma prática recomendada de segurança.
As permissões concedidas a um cliente que possui a SAS são a interseção das permissões concedidas à entidade de segurança que solicitou a chave de delegação do usuário e as permissões que foram concedidas ao recurso no token SAS usando o campo signedPermissions (sp). Se uma permissão concedida à entidade de segurança por meio de ACLs RBAC ou POSIX também não for concedida no token SAS, essa permissão não será concedida ao cliente que tenta usar a SAS para acessar o recurso. Ao criar uma SAS de delegação de usuário, verifique se as permissões concedidas por meio de ACLs RBAC e POSIX e as permissões concedidas por meio do token SAS se alinham ao nível de acesso exigido pelo cliente.
Para criar uma SAS de delegação de usuário, faça o seguinte:
- Use ACLs RBAC ou POSIX para conceder as permissões desejadas à entidade de segurança que solicitará a chave de delegação do usuário.
- Adquira um token OAuth 2.0 da ID do Microsoft Entra.
- Use o token para solicitar a chave de delegação do usuário chamando a operação Obter Chave de Delegação de Usuário.
- Use a chave de delegação do usuário para construir o token SAS com os campos apropriados.
Atribuir permissões com RBAC
A entidade de segurança que solicita a chave de delegação do usuário precisa ter as permissões apropriadas para fazer isso. Uma entidade de segurança do Microsoft Entra ID pode ser um usuário, um grupo, uma entidade de serviço ou uma identidade gerenciada.
Para solicitar a chave de delegação do usuário, você deve atribuir a uma entidade de segurança a ação Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey. As funções RBAC internas a seguir incluem a ação Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey, explicitamente ou como parte de uma definição curinga:
- Colaborador
- Colaborador da Conta de Armazenamento
- Colaborador de dados de blob de armazenamento
- proprietário de dados de blob de armazenamento
- de Leitor de Dados de Blobs de Armazenamento
- de Delegador de Blobs de Armazenamento
Como a operação Obter Chave de Delegação de Usuário atua no nível da conta de armazenamento, a ação Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey deve ser definida no nível da conta de armazenamento, do grupo de recursos ou da assinatura. Se a entidade de segurança receber qualquer uma das funções internas listadas anteriormente ou uma função personalizada que inclua o Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey ação, no nível da conta de armazenamento, do grupo de recursos ou da assinatura, a entidade de segurança poderá solicitar a chave de delegação do usuário.
Se a entidade de segurança receber uma função que permita acesso a dados, mas estiver no escopo do nível de um contêiner, você também poderá atribuir a função Delegador de Blobs de Armazenamento à entidade de segurança no nível da conta de armazenamento, grupo de recursos ou assinatura. A função Delegador de Blobs de Armazenamento concede às entidades de segurança permissões para solicitar a chave de delegação do usuário.
Para obter mais informações sobre as funções RBAC para o Armazenamento do Azure, consulte Autorizar com o Microsoft Entra.
Adquirir um token OAuth 2.0
Para obter a chave de delegação do usuário, primeiro solicite um token OAuth 2.0 da ID do Microsoft Entra. Forneça o token com o esquema de portador para autorizar a chamada para a operação Obter Chave de Delegação de Usuário
Solicitar a chave de delegação do usuário
Uma chamada para a operação Obter Chave de Delegação de Usuário retorna a chave como um conjunto de valores que são usados como parâmetros no token SAS de delegação do usuário. Esses parâmetros são descritos na referência Obter Chave de Delegação de Usuário e, na próxima seção, "Construir uma SAS de delegação de usuário".
Quando um cliente solicita uma chave de delegação de usuário usando um token OAuth 2.0, o Armazenamento do Azure retorna a chave de delegação do usuário em nome da entidade de segurança. A SAS criada com a chave de delegação do usuário recebe as permissões concedidas à entidade de segurança.
Depois de ter a chave de delegação do usuário, você poderá usá-la para criar qualquer número de assinaturas de acesso compartilhado de delegação de usuário ao longo do tempo de vida da chave. A chave de delegação do usuário é independente do token OAuth 2.0 que você usa para adquiri-la, portanto, o token não precisa ser renovado desde que a chave ainda seja válida. Você pode especificar que a chave é válida por um período de até sete dias.
Construir uma SAS de delegação de usuário
A tabela a seguir resume os campos com suporte para um token SAS de delegação de usuário. As seções subsequentes fornecem detalhes adicionais sobre como especificar esses parâmetros.
| Nome do campo SAS | Parâmetro de token SAS | Obrigatória ou opcional | Suporte à versão | Descrição |
|---|---|---|---|---|
signedVersion |
sv |
Obrigatória | 2018-11-09 e posterior | Indica a versão do serviço usada para construir o campo de assinatura. Ele também especifica a versão de serviço que manipula solicitações feitas com essa SAS. |
signedResource |
sr |
Obrigatória | Todos | Especifica quais recursos de blob são acessíveis por meio da assinatura de acesso compartilhado. |
signedStart |
st |
Opcional | Todos | 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 valor for omitido, a hora UTC atual será usada como a hora de início. Para obter mais informações sobre formatos UTC aceitos, consulte Formatar valores datetime. |
signedExpiry |
se |
Obrigatória | Todos | A hora em que a assinatura de acesso compartilhado se torna inválida, expressa em um dos formatos UTC ISO 8601 aceitos. Para obter mais informações sobre formatos UTC aceitos, consulte Formatar valores datetime. |
signedPermissions |
sp |
Obrigatória | Todos | Indica quais operações um cliente que possui a SAS pode executar no recurso. As permissões podem ser combinadas. |
signedIp |
sip |
Opcional | 2015-04-05 e posterior | Especifica um endereço IP ou um intervalo inclusivo de endereços IP dos quais aceitar solicitações. Ao especificar um intervalo, tenha em mente que o intervalo é inclusivo. Há suporte apenas para endereços IPv4. Por exemplo, sip=198.51.100.0 ou sip=198.51.100.10-198.51.100.20. |
signedProtocol |
spr |
Opcional | 2015-04-05 e posterior | Especifica o protocolo permitido para uma solicitação feita com a SAS. Inclua esse campo para exigir que as solicitações feitas com o token SAS usem HTTPS. |
signedObjectId |
skoid |
Obrigatória | 2018-11-09 e posterior | Especifica a ID do objeto para uma entidade de segurança do Microsoft Entra. Essa ID de objeto corresponde à entidade de segurança que solicitou a chave de delegação do usuário. Antes de autorizar a operação, o Armazenamento do Azure verifica as permissões RBAC na ID do objeto. Se as permissões RBAC não puderem conceder acesso, o Armazenamento do Azure verificará as permissões DE ACL POSIX na ID do objeto. |
signedTenantId |
sktid |
Obrigatória | 2018-11-09 e posterior | Especifica o locatário do Microsoft Entra no qual uma entidade de segurança é definida. |
signedKeyStartTime |
skt |
Obrigatória. | 2018-11-09 e posterior | O valor é retornado pela operação Obter Chave de Delegação de Usuário |
signedKeyExpiryTime |
ske |
Obrigatória | 2018-11-09 e posterior | O valor é retornado pela operação Obter Chave de Delegação de Usuário |
signedKeyVersion |
skv |
Obrigatória | 2018-11-09 e posterior | O valor é retornado pela operação Obter Chave de Delegação de Usuário |
signedKeyService |
sks |
Obrigatória | 2018-11-09 e posterior | Indica o serviço para o qual a chave de delegação do usuário é válida. Atualmente, há suporte apenas para o Armazenamento de Blobs. |
signedAuthorizedObjectId |
saoid |
Opcional | 2020-02-10 e posterior | Especifica a ID do objeto de uma entidade de segurança do Microsoft Entra autorizada pelo proprietário da chave de delegação do usuário a executar a ação concedida pelo token SAS. Essa ID de objeto corresponde à entidade de segurança do usuário final da SAS. Nenhuma verificação de permissão adicional nas ACLs (listas de controle de acesso) POSIX é executada. |
signedUnauthorizedObjectId |
suoid |
Opcional | 2020-02-10 e posterior | Especifica a ID do objeto para uma entidade de segurança do Microsoft Entra quando um namespace hierárquico está habilitado. Essa ID de objeto corresponde à entidade de segurança do usuário final da SAS. O Armazenamento do Azure executa uma verificação de ACL POSIX na ID do objeto antes de autorizar a operação. |
signedCorrelationId |
scid |
Opcional | 2020-02-10 e posterior | Correlacionar os logs de auditoria de armazenamento com os logs de auditoria usados pela entidade de segurança que gera e distribui a SAS. |
signedDirectoryDepth |
sdd |
Necessário quando sr=d |
2020-02-10 e posterior | Indica o número de diretórios dentro da pasta raiz do diretório especificado no campo canonicalizedResource da cadeia de caracteres para o sinal. |
signedEncryptionScope |
ses |
Opcional | 2020-12-06 e posterior | Indica o escopo de criptografia a ser usado para criptografar o conteúdo da solicitação. |
signature |
sig |
Obrigatória | Todos | A assinatura é um HMAC (código de autenticação de mensagem baseado em hash) que é computado na cadeia de caracteres para assinar e na chave usando o algoritmo SHA256 e codificado usando a codificação Base64. |
cabeçalho de resposta Cache-Control |
rscc |
Opcional | 2013-08-15 e posterior | O Armazenamento do Azure define o cabeçalho de resposta Cache-Control para o valor especificado no token SAS. |
cabeçalho de resposta Content-Disposition |
rscd |
Opcional | 2013-08-15 e posterior | O Armazenamento do Azure define o cabeçalho de resposta Content-Disposition para o valor especificado no token SAS. |
cabeçalho de resposta Content-Encoding |
rsce |
Opcional | 2013-08-15 e posterior | O Armazenamento do Azure define o cabeçalho de resposta Content-Encoding para o valor especificado no token SAS. |
cabeçalho de resposta Content-Language |
rscl |
Opcional | 2013-08-15 e posterior | O Armazenamento do Azure define o cabeçalho de resposta Content-Language para o valor especificado no token SAS. |
cabeçalho de resposta Content-Type |
rsct |
Opcional | 2013-08-15 e posterior | O Armazenamento do Azure define o cabeçalho de resposta Content-Type para o valor especificado no token SAS. |
Especificar o campo de versão assinada
O campo signedVersion (sv) necessário especifica a versão do serviço para a assinatura de acesso compartilhado. Esse valor indica a versão do serviço usada para construir o campo signature e especifica a versão de serviço que manipula uma solicitação feita com essa assinatura de acesso compartilhado. O valor do campo sv deve ser a versão 2018-11-09 ou posterior.
Especificar o campo de recurso assinado
O campo signedResource (sr) necessário 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, contêiner ou diretório no token SAS:
| Recurso | Valor do parâmetro | Versões suportadas | Descrição |
|---|---|---|---|
| Blob | b | Todos | 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 blob | Bs | 2018-11-09 e posterior | Concede acesso ao conteúdo e aos metadados do instantâneo de blob, mas não ao blob base. |
| Contêiner | c | Todos | 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 campo signedResource, o parâmetro signedDirectoryDepth (sdd) também será necessário. Um diretório está sempre dentro de um contêiner. |
Especificar a duração da validade da assinatura
Os campos signedStart (st) e signedExpiry (se) indicam os tempos de início e expiração para a SAS. O campo signedExpiry é necessário. O campo signedStart é opcional. Se for omitido, a hora UTC atual será usada como a hora de início.
Para uma SAS de delegação de usuário, os tempos de início e de expiração para a SAS devem estar dentro do intervalo definido para a chave de delegação do usuário. Se um cliente tentar usar uma SAS depois que a chave de delegação do usuário tiver expirado, a SAS falhará com um erro de autorização, independentemente de a SAS em si ainda ser válida.
Para obter mais informações sobre formatos UTC aceitos, consulte Formatar valores datetime.
Especificar permissões
As permissões especificadas para o campo signedPermissions (sp) no token SAS indicam quais operações um cliente que possui a SAS pode executar no recurso.
As permissões podem ser combinadas 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. Especificar uma designação de permissão mais de uma vez não é permitido.
Uma SAS de delegação de usuário não pode conceder acesso a determinadas operações:
- Os contêineres não podem ser criados, excluídos ou listados.
- Os metadados e as propriedades do contêiner não podem ser lidos ou 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, consulte Criar uma conta sas.
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 |
Todos | 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 |
Todos | Adicione um bloco a um blob de acréscimo. |
| Criar | c | Contêiner Diretório Blob |
Todos | Escreva um novo blob, instantâneo de um blob ou copie um blob para um novo blob. |
| Gravar | w | Contêiner Diretório Blob |
Todos | Criar ou gravar conteúdo, propriedades, metadados ou lista de bloqueios. Instantâneo ou concessão do blob. Redimensione o blob (somente blob de página). Use o blob como o destino de uma operação de cópia. |
| Excluir | d | Contêiner Diretório Blob |
Todos | 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 de |
| Excluir versão | x | Contêiner Blob |
2019-12-12 e posterior | Exclua uma versão de blob. |
| Exclusão permanente | y | Blob | 2020-02-10 e posterior | Exclua permanentemente um instantâneo de blob ou uma versão. |
| Lista | l | Contêiner Diretório |
Todos | Listar blobs de forma não recursiva. |
| Marcações | t | Blob | 2019-12-12 e posterior | Ler ou gravar as marcas em um blob. |
| 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 pai, diretório ou blob filho se o parâmetro saoid estiver incluído no token SAS e o bit autoadesiva estiver definido no diretório pai. |
| 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. Ele 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 quando o chamador renomeia ou exclua um diretório ou blob dentro de um diretório que tenha o conjunto de bits autoadesivo. |
| 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 | eu | Contêiner Blob |
2020-06-12 e posterior | Defina ou exclua a política de imutabilidade ou a retenção legal em um blob. |
Especificar um endereço IP ou intervalo de IP
O campo signedIp opcional (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 apenas para endereços IPv4.
Quando você especifica um intervalo de endereços IP, o intervalo é inclusivo. Por exemplo, especificar sip=198.51.100.0 ou sip=198.51.100.10-198.51.100.20 na SAS restringe a solicitação a esses endereços IP.
A tabela a seguir descreve se o campo signedIp deve ser incluído em um token SAS para um determinado cenário, 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 campo signedIp. As solicitações que você faz de dentro da mesma região usando uma SAS com um endereço IP de saída especificado falham.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 campo signedIp. As solicitações que você faz com a SAS devem 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 campo signedIp. As solicitações que você faz com a SAS devem 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 campo signedIp. |
Especificar o protocolo HTTP
O campo signedProtocol opcional (spr) especifica o protocolo permitido para solicitações feitas com a SAS. Os valores possíveis são HTTPS e HTTP (https,http) ou somente HTTPS (https). O valor padrão é https,http.
Observação
Não é possível especificar HTTP para o campo spr.
Especificar a ID do objeto assinado
O campo signedObjectId (skoid) é necessário para uma SAS de delegação de usuário. A operação Obter Chave de Delegação de Usuário retorna esse valor como parte da resposta. A ID do objeto assinado é um valor GUID que serve o identificador imutável para uma entidade de segurança na plataforma de identidade da Microsoft.
Especificar a ID do locatário assinado
O campo signedTenantId (sktid) é necessário para uma SAS de delegação de usuário. A operação Obter Chave de Delegação de Usuário retorna esse valor como parte da resposta. A ID do locatário assinado é um valor GUID que representa o locatário do Microsoft Entra no qual uma entidade de segurança é definida.
Especificar a hora de início da chave assinada
O campo signedKeyStartTime (skt) necessário indica o início do tempo de vida da chave de delegação do usuário no formato data ISO. A operação Obter Chave de Delegação de Usuário retorna esse valor como parte da resposta.
Especificar o tempo de expiração da chave assinada
O campo signedKeyExpiryTime (ske) é necessário para uma SAS de delegação de usuário no formato data ISO. A operação Obter Chave de Delegação de Usuário retorna esse valor como parte da resposta. O tempo de expiração da chave assinada indica o fim do tempo de vida da chave de delegação do usuário. O valor do tempo de expiração pode ser um máximo de sete dias a partir da hora de início da SAS.
Especificar o serviço de chave assinada
O campo signedKeyService (sks) é necessário para uma SAS de delegação de usuário. A operação Obter Chave de Delegação de Usuário retorna esse valor como parte da resposta. O campo de serviço de chave assinada indica o serviço para o qual a chave de delegação do usuário é válida. O valor do campo de serviço de chave assinada para o Armazenamento de Blobs é b.
Especificar a versão da chave assinada
O campo signedkeyversion (skv) é necessário para uma SAS de delegação de usuário. A operação Obter Chave de Delegação de Usuário retorna esse valor como parte da resposta. O campo signedkeyversion especifica a versão do serviço de armazenamento usada para obter a chave de delegação do usuário. Esse campo deve especificar a versão 2018-11-09 ou posterior.
Especificar uma ID de objeto de usuário assinada para uma entidade de segurança
Os campos opcionais signedAuthorizedObjectId (saoid) e signedUnauthorizedObjectId (suoid) permitem a integração com o Apache Hadoop e o Apache Ranger para cargas de trabalho do Azure Data Lake Storage. Use um desses campos no token SAS para especificar a ID do objeto para uma entidade de segurança:
- O campo
saoidespecifica a ID do objeto para uma entidade de segurança do Microsoft Entra autorizada pelo proprietário da chave de delegação do usuário a executar a ação concedida pelo token SAS. O Armazenamento do Azure valida o token SAS e garante que o proprietário da chave de delegação de usuário tenha as permissões necessárias antes que o Armazenamento do Azure conceda acesso. Nenhuma verificação de permissão adicional em ACLs POSIX é executada. - O campo
suoidespecifica a ID do objeto para uma entidade de segurança do Microsoft Entra quando um namespace hierárquico está habilitado para uma conta de armazenamento. O camposuoidé válido apenas para contas que têm um namespace hierárquico. Quando o camposuoidé incluído no token SAS, o Armazenamento do Azure executa uma verificação de ACL POSIX na ID do objeto antes de autorizar a operação. Se essa verificação de ACL não for bem-sucedida, a operação falhará. Um namespace hierárquico deve ser habilitado para a conta de armazenamento se o camposuoidestiver incluído no token SAS. Caso contrário, a verificação de permissão falhará com um erro de autorização.
A ID do objeto da entidade de segurança que solicita a chave de delegação do usuário é capturada no campo skoid necessário. Para especificar uma ID de objeto no token SAS com o campo saoid ou suoid, a entidade de segurança identificada no campo skoid deve receber uma função RBAC que inclua Microsoft.Storage/storageAccounts/blobServices/containers/blobs/runAsSuperUser/action ou Microsoft.Storage/storageAccounts/blobServices/containers/blobs/manageOwnership/action. Para obter mais informações sobre essas ações, consulte operações do provedor de recursos do Azure.
Ao especificar a ID do objeto no campo saoid ou suoid, você também restringe as operações relacionadas à propriedade de diretório ou blob das seguintes maneiras:
- Se uma operação criar um diretório ou blob, o Armazenamento do Azure definirá o proprietário do diretório ou blob como o valor especificado pela ID do objeto. Se a ID do objeto não for especificada, o Armazenamento do Azure definirá o proprietário do diretório ou blob como o valor especificado pelo parâmetro
skoid. - Se o bit autoadesiva estiver definido no diretório pai e a operação excluir ou renomear um diretório ou blob, a ID do objeto do proprietário do diretório pai ou do proprietário do recurso deverá corresponder ao valor especificado pela ID do objeto.
- Se uma operação definir o proprietário de um diretório ou blob e o cabeçalho
x-ms-ownerfor especificado, o valor especificado pela ID do objeto deverá corresponder ao valor especificado pelo cabeçalhox-ms-owner. - Se uma operação definir o grupo para um diretório ou blob e o cabeçalho
x-ms-groupfor especificado, o valor especificado pela ID do objeto deverá ser um membro do grupo especificado pelo cabeçalhox-ms-group. - Se uma operação definir as permissões ou ACL para um diretório ou blob, uma das duas seguintes condições também deverá ser atendida:
- O valor especificado para a ID do objeto deve ser o proprietário do diretório ou blob.
- O valor do campo
signedPermissions(sp) deve incluir a permissãoOwnership(o) além da permissãoPermissions(p).
A ID do objeto especificada no campo saoid ou suoid é incluída nos logs de diagnóstico quando você faz solicitações usando o token SAS.
O campo saoid ou suoid só terá suporte se o campo signedVersion (sv) estiver definido como versão 2020-02-10 ou posterior. Somente um desses campos pode ser incluído no token SAS.
Especificar uma ID de correlação
O campo signedCorrelationId (scid) especifica uma ID de correlação que pode ser usada para correlacionar os logs de auditoria de armazenamento com os logs de auditoria usados pela entidade de segurança que gera e distribui a SAS. Por exemplo, um serviço de autorização confiável normalmente tem uma identidade gerenciada que autentica e autoriza usuários, gera uma SAS, adiciona uma entrada ao log de auditoria local e retorna a SAS a um usuário, que pode usar a SAS para acessar os recursos do Armazenamento do Azure. Ao incluir uma ID de correlação no log de auditoria local e no log de auditoria de armazenamento, você permite que esses eventos sejam correlacionados posteriormente. O valor é um GUID sem chaves e com caracteres minúsculos.
Esse campo tem suporte com a versão 2020-02-10 e posterior.
Especificar a profundidade do diretório
Se o campo signedResource especificar um diretório (sr=d), você também deverá especificar o campo signedDirectoryDepth (sdd) para indicar o número de subdiretórios no diretório raiz. O valor do campo sdd deve ser um inteiro não negativo.
Por exemplo, o diretório raiz https://{account}.blob.core.windows.net/{container}/ tem uma profundidade de 0. Cada subdiretório dentro do diretório raiz adiciona a profundidade em 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 e posterior.
Especificar parâmetros de consulta para substituir cabeçalhos de resposta
Para definir valores para determinados cabeçalhos de resposta a serem retornados quando a assinatura de acesso compartilhado for usada em uma solicitação, você pode especificar cabeçalhos de resposta em parâmetros de consulta. Os cabeçalhos de resposta e os parâmetros de consulta correspondentes são os seguintes:
| Nome do cabeçalho de 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 você especificar o parâmetro de consulta rsct=binary em um token SAS, o cabeçalho de resposta Content-Type será definido como binary. Esse valor substitui o valor de cabeçalho Content-Type armazenado para o blob para uma solicitação usando apenas essa assinatura de acesso compartilhado.
Se você criar uma assinatura de acesso compartilhado que especifique cabeçalhos de resposta como parâmetros de consulta, deverá incluir esses cabeçalhos de resposta no sinal de cadeia de caracteres que é usado para construir a cadeia de caracteres de assinatura. Para obter mais informações, consulte a seção "Especificar a assinatura".
Especificar o escopo de criptografia
O campo signed encryption scope tem suporte quando o campo de versão assinada (sv) no token SAS é a versão 2020-12-06 ou posterior. Se o campo de versão assinada especificar uma versão anterior à versão com suporte, o serviço retornará o código de resposta de erro 403 (Proibido).
Se o escopo de criptografia padrão for definido para o contêiner ou o sistema de arquivos, o campo ses respeitará a política de criptografia de contêiner. Se houver uma incompatibilidade entre o parâmetro de consulta ses e o cabeçalho x-ms-default-encryption-scope e o cabeçalho x-ms-deny-encryption-scope-override estiver definido como true, o serviço retornará o código de resposta de erro 403 (Proibido).
Se o cabeçalho x-ms-encryption-scope e o parâmetro de consulta ses forem fornecidos na solicitação PUT e houver uma incompatibilidade, o serviço retornará o código de resposta de erro 400 (Solicitação Incorreta).
Especificar a assinatura
O campo signature (sig) é usado para autorizar uma solicitação feita por um cliente com a assinatura de acesso compartilhado. A cadeia de caracteres a assinar é uma cadeia de caracteres exclusiva que é construída a partir dos campos que devem ser verificados para autorizar a solicitação. A assinatura é um HMAC que é computado sobre a cadeia de caracteres para assinar e a chave usando o algoritmo SHA256 e codificado usando a codificação Base64.
Para construir a cadeia de caracteres de assinatura de uma SAS de delegação de usuário, crie 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 compute a assinatura usando o algoritmo HMAC-SHA256. Os campos incluídos na cadeia de caracteres a assinar devem ser decodificados por URL.
Os campos que são necessários na cadeia de caracteres para assinar dependem da versão de serviço usada para autorização (sv campo). As seções a seguir descrevem a configuração de cadeia de caracteres para assinar para versões que dão suporte à SAS de delegação de usuário.
Versão 2020-12-06 e posterior
A cadeia de caracteres para assinar para a versão de autorização 2020-12-06 e posterior tem o seguinte formato:
StringToSign = signedPermissions + "\n" +
signedStart + "\n" +
signedExpiry + "\n" +
canonicalizedResource + "\n" +
signedKeyObjectId + "\n" +
signedKeyTenantId + "\n" +
signedKeyStart + "\n" +
signedKeyExpiry + "\n" +
signedKeyService + "\n" +
signedKeyVersion + "\n" +
signedAuthorizedUserObjectId + "\n" +
signedUnauthorizedUserObjectId + "\n" +
signedCorrelationId + "\n" +
signedIP + "\n" +
signedProtocol + "\n" +
signedVersion + "\n" +
signedResource + "\n" +
signedSnapshotTime + "\n" +
signedEncryptionScope + "\n" +
rscc + "\n" +
rscd + "\n" +
rsce + "\n" +
rscl + "\n" +
rsct
Versão 2020-02-10
A cadeia de caracteres para assinar para a versão de autorização 2020-02-10 tem o seguinte formato:
StringToSign = signedPermissions + "\n" +
signedStart + "\n" +
signedExpiry + "\n" +
canonicalizedResource + "\n" +
signedKeyObjectId + "\n" +
signedKeyTenantId + "\n" +
signedKeyStart + "\n" +
signedKeyExpiry + "\n" +
signedKeyService + "\n" +
signedKeyVersion + "\n" +
signedAuthorizedUserObjectId + "\n" +
signedUnauthorizedUserObjectId + "\n" +
signedCorrelationId + "\n" +
signedIP + "\n" +
signedProtocol + "\n" +
signedVersion + "\n" +
signedResource + "\n" +
signedSnapshotTime + "\n" +
rscc + "\n" +
rscd + "\n" +
rsce + "\n" +
rscl + "\n" +
rsct
Versões anteriores a 2020-02-10
A cadeia de caracteres para assinar para versões de autorização anteriores a 2020-02-10 tem o seguinte formato:
StringToSign = signedPermissions + "\n" +
signedStart + "\n" +
signedExpiry + "\n" +
canonicalizedResource + "\n" +
signedKeyObjectId + "\n" +
signedKeyTenantId + "\n" +
signedKeyStart + "\n" +
signedKeyExpiry + "\n" +
signedKeyService + "\n" +
signedKeyVersion + "\n" +
signedAuthorizedUserObjectId + "\n" +
signedUnauthorizedUserObjectId + "\n" +
signedCorrelationId + "\n" +
signedIP + "\n" +
signedProtocol + "\n" +
signedVersion + "\n" +
signedResource + "\n" +
rscc + "\n" +
rscd + "\n" +
rsce + "\n" +
rscl + "\n" +
rsct
Recurso canonizado
A parte canonicalizedResource da cadeia de caracteres é um caminho canônico para o recurso assinado. Ele deve incluir o ponto de extremidade do Armazenamento de Blobs e o nome do recurso e deve ser decodificado por URL. Um caminho de blob deve incluir seu contêiner. Um caminho de diretório deve incluir o número de subdiretórios que correspondem ao parâmetro sdd.
A cadeia de caracteres de recurso canônica para um contêiner deve omitir a barra à direita (/) para uma SAS que fornece acesso a esse contêiner.
Os exemplos a seguir mostram como construir a parte canonicalizedResource da cadeia de caracteres, dependendo do tipo de recurso.
Exemplo de contêiner (Armazenamento de Blobs do Azure)
URL = https://myaccount.blob.core.windows.net/music
canonicalizedResource = "/blob/myaccount/music"
Exemplo de blob (Armazenamento de Blobs do Azure)
URL = https://myaccount.blob.core.windows.net/music/intro.mp3
canonicalizedResource = "/blob/myaccount/music/intro.mp3"
Exemplo de contêiner (Azure Data Lake Storage)
URL = https://myaccount.dfs.core.windows.net/music
canonicalizedResource = "/blob/myaccount/music"
Exemplo de diretório (Azure Data Lake Storage)
URL = https://myaccount.dfs.core.windows.net/music/instruments/guitar/
canonicalizedResource = "/blob/myaccount/music/instruments/guitar/"
Exemplo de blob (Azure Data Lake Storage)
URL = https://myaccount.dfs.core.windows.net/music/intro.mp3
canonicalizedResource = "/blob/myaccount/music/intro.mp3"
Campos opcionais
Se um campo for opcional e não for fornecido como parte do token SAS, especifique uma cadeia de caracteres vazia para o campo. Certifique-se de incluir o caractere de nova linha (\n) após a cadeia de caracteres vazia.
Exemplo de SAS de delegação de usuário
O exemplo a seguir mostra um URI de blob com um token SAS de delegação de usuário acrescentado a ele. O token SAS de delegação de usuário 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&skoid=<object-id>&sktid=<tenant-id>&skt=2023-05-24T01:13:55Z&ske=2023-05-24T09:13:55Z&sks=b&skv=2022-11-02&sip=198.51.100.10-198.51.100.20&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 do 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 pela SAS incluem Leitura (r) e Gravação (w). |
| Hora de início | st=2023-05-24T01:13:55Z |
Especificado no horário UTC. Se você quiser que a SAS seja válida imediatamente, omita a hora de início. |
| Tempo de expiração | se=2023-05-24T09:13:55Z |
Especificado no horário UTC. |
| ID de objeto | skoid=<object-id> |
Uma entidade de segurança do Microsoft Entra. |
| ID do locatário | sktid=<tenant-id> |
O locatário do Microsoft Entra no qual a entidade de segurança está registrada. |
| Hora de início da chave | skt=2023-05-24T01:13:55Z |
O início do tempo de vida da chave de delegação do usuário. |
| Hora de expiração da chave | ske=2023-05-24T09:13:55Z |
O fim do tempo de vida da chave de delegação do usuário. |
| Serviço de chave | sks=b |
Somente o serviço Blob tem suporte para o valor do serviço. |
| Versão da chave | skv=2022-11-02 |
A versão do serviço de armazenamento usada para obter a chave de delegação do usuário. |
| Intervalo de IP | sip=198.51.100.10-198.51.100.20 |
O intervalo de endereços IP dos quais uma solicitação será aceita. |
| Protocolo | spr=https |
Somente solicitações que usam HTTPS são permitidas. |
| Versão do serviço blob | sv=2022-11-02 |
Para o Armazenamento do Azure versão 2012-02-12 e posterior, esse parâmetro indica a versão a ser usada. |
| Recurso | sr=b |
O recurso é um blob. |
| Assinatura | sig=<signature> |
Usado para autorizar o acesso ao blob. A assinatura é um HMAC que é computado em uma cadeia de caracteres para sinal e chave usando o algoritmo SHA256 e codificado usando a codificação Base64. |
Revogar uma SAS de delegação de usuário
Se você acredita que uma SAS foi comprometida, você deve revogá-la. Você pode revogar uma SAS de delegação de usuário revogando a chave de delegação do usuário ou alterando ou removendo atribuições de função RBAC e ACLs POSIX para a entidade de segurança usada para criar a SAS.
Importante
Tanto a chave de delegação de usuário quanto as atribuições de função RBAC são armazenadas em cache pelo Armazenamento do Azure, portanto, pode haver um atraso entre quando você inicia o processo de revogação e quando uma SAS de delegação de usuário existente se torna inválida.
Revogar a chave de delegação do usuário
Você pode revogar a chave de delegação do usuário chamando a operação Revogar Chaves de Delegação de Usuário
Alterar ou remover atribuições de função ou ACLs
Você pode alterar ou remover a atribuição de função RBAC e as ACLs POSIX para a entidade de segurança usada para criar a SAS. Quando um cliente usa a SAS para acessar um recurso, o Armazenamento do Azure verifica se a entidade de segurança cujas credenciais foram usadas para proteger a SAS tem as permissões necessárias para o recurso.