Criar uma SAS de delegação de usuário

  • Artigo

Você pode proteger um token SAS (assinatura de acesso compartilhado) para acesso a um contêiner, diretório ou blob usando Microsoft Entra credenciais ou uma chave de conta. Uma SAS protegida com credenciais de Microsoft Entra é chamada de SAS de delegação de usuário. Como prática recomendada de segurança, recomendamos que você use Microsoft Entra credenciais quando possível, em vez da chave de conta, que pode ser comprometida com mais facilidade. Quando o design do aplicativo exigir assinaturas de acesso compartilhado, use Microsoft Entra credenciais 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 de 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 de 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 de usuário para criar a SAS.

Há suporte para UMA SAS de delegação de usuário para Armazenamento de Blobs do Azure e Azure Data Lake Storage Gen2. Não há suporte para políticas de acesso armazenadas 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 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 os URIs de assinatura de acesso compartilhado só devem ser distribuídos em uma conexão segura, como HTTPS.

Para obter informações sobre como usar sua chave de conta para proteger uma SAS, consulte Criar uma SAS de serviço e Criar uma SAS de conta.

Suporte a SAS de delegação de usuário para acesso no escopo do 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) é 2020-02-10 ou posterior e um HNS (namespace hierárquico) está 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 todos os 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.

Suporte a SAS de delegação de usuário para um 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 é carregado no saoid parâmetro ou suoid quando a versão de autorização (sv) é 2020-02-10 ou posterior. Esse parâmetro opcional fornece 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.

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 de Microsoft Entra que foram usadas para criar a SAS. As permissões rbac (controle de acesso baseado em função) concedidas para essa conta Microsoft Entra, juntamente com as permissões explicitamente concedidas na SAS, determinam o acesso do cliente ao recurso. Essa abordagem fornece um nível adicional de segurança e ajuda você a evitar a necessidade de armazenar a chave de acesso da conta com o código do aplicativo. Por esses motivos, criar uma SAS usando Microsoft Entra credenciais é 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 que foram 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 signedPermissions campo (sp). Se uma permissão concedida à entidade de segurança por meio do RBAC não for concedida também 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 do RBAC 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:

  1. Use o RBAC para conceder as permissões desejadas à entidade de segurança que solicitará a chave de delegação do usuário.
  2. Adquira um token OAuth 2.0 de Microsoft Entra ID.
  3. 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 .
  4. Use a chave de delegação de 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 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 seguintes funções RBAC internas incluem a ação Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey , explicitamente ou como parte de uma definição curinga:

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 ter o escopo definido no nível da conta de armazenamento, do grupo de recursos ou da assinatura. Se a entidade de segurança for atribuída a qualquer uma das funções internas listadas anteriormente ou uma função personalizada que inclua a ação Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey , 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 o acesso a dados, mas estiver no escopo do nível de um contêiner, você também poderá atribuir a função de Delegador de Blob de Armazenamento à entidade de segurança no nível da conta de armazenamento, do grupo de recursos ou da assinatura. A função Delegador de Blob de Armazenamento concede as permissões da entidade de segurança para solicitar a chave de delegação do usuário.

Para obter mais informações sobre funções RBAC para o Armazenamento do Azure, consulte Autorizar com o Azure Active Directory.

Adquirir um token OAuth 2.0

Para obter a chave de delegação do usuário, primeiro solicite um token OAuth 2.0 do Microsoft Entra ID. 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 . Para obter mais informações sobre como solicitar um token OAuth de Microsoft Entra ID, consulte Fluxos de autenticação e cenários de aplicativo.

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 de usuário em nome da entidade de segurança. A SAS criada com a chave de delegação de usuário recebe as permissões que foram concedidas à entidade de segurança.

Depois de ter a chave de delegação de usuário, você pode usá-la para criar qualquer número de assinaturas de acesso compartilhado de delegação de usuário durante o tempo de vida da chave. A chave de delegação de 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ório ou opcional Suporte à versão Descrição
signedVersion sv Obrigatório 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 do serviço que lida com solicitações feitas com essa SAS.
signedResource sr Obrigatório Todos Especifica quais recursos de blob podem ser acessados por meio da assinatura de acesso compartilhado.
signedStart st Opcional Tudo 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ório 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ório 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 somente para endereços IPv4.

Por exemplo, sip=168.1.5.65 ou sip=168.1.5.60-168.1.5.70.
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ório 2018-11-09 e posterior Identifica uma entidade de segurança Microsoft Entra.
signedTenantId sktid Obrigatório 2018-11-09 e posterior Especifica o locatário Microsoft Entra no qual uma entidade de segurança é definida.
signedKeyStartTime skt Opcional. 2018-11-09 e posterior O valor é retornado pela operação Obter Chave de Delegação de Usuário . Indica o início do tempo de vida da chave de delegação do usuário, expresso em um dos formatos UTC ISO 8601 aceitos. Se o valor for omitido, a hora atual será assumida. Para obter mais informações sobre formatos UTC aceitos, consulte Formatar valores datetime.
signedKeyExpiryTime ske Obrigatório 2018-11-09 e posterior O valor é retornado pela operação Obter Chave de Delegação de Usuário . Indica o fim do tempo de vida da chave de delegação do usuário, expresso em um dos formatos ISO 8601 UTC aceitos. Para obter mais informações sobre formatos UTC aceitos, consulte Formatar valores datetime.
signedKeyVersion skv Obrigatório 2018-11-09 e posterior O valor é retornado pela operação Obter Chave de Delegação de Usuário . Especifica a versão do serviço de armazenamento que foi usada para obter a chave de delegação do usuário. Esse campo deve especificar a versão 2018-11-09 ou posterior.
signedKeyService sks Obrigatório 2018-11-09 e posterior Indica o serviço para o qual a chave de delegação de usuário é válida. Atualmente, há suporte apenas para o Armazenamento de Blobs.
signedAuthorizedObjectId saoid Opcional 2020-02-10 e posterior Especifica a ID de objeto de uma entidade de segurança Microsoft Entra autorizada pelo proprietário da chave de delegação de usuário para executar a ação concedida pelo token SAS. Nenhuma permissão adicional marcar em ACLs (listas de controle de acesso) POSIX (Portable Operating System Interface) é executada.
signedUnauthorizedObjectId suoid Opcional 2020-02-10 e posterior Especifica a ID do objeto de uma entidade de segurança Microsoft Entra quando um namespace hierárquico está habilitado. O Armazenamento do Azure executa uma ACL POSIX marcar na ID do objeto antes de autorizar a operação.
signedCorrelationId scid Opcional 2020-02-10 e posterior Correlacione 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 Obrigató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 canonicalizedResource campo da cadeia de caracteres a assinar.
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ório Todos A assinatura é um HMAC (código de autenticação de mensagem baseado em hash) que é calculado sobre a cadeia de caracteres para assinar e a chave usando o algoritmo SHA256 e, em seguida, codificado usando a codificação Base64.
Cache-Control cabeçalho de resposta rscc Opcional 2013-08-15 e posterior O Armazenamento do Azure define o Cache-Control cabeçalho de resposta como o valor especificado no token SAS.
Content-Disposition cabeçalho de resposta rscd Opcional 2013-08-15 e posterior O Armazenamento do Azure define o Content-Disposition cabeçalho de resposta como o valor especificado no token SAS.
Content-Encoding cabeçalho de resposta rsce Opcional 2013-08-15 e posterior O Armazenamento do Azure define o Content-Encoding cabeçalho de resposta como o valor especificado no token SAS.
Content-Language cabeçalho de resposta rscl Opcional 2013-08-15 e posterior O Armazenamento do Azure define o Content-Language cabeçalho de resposta como o valor especificado no token SAS.
Content-Type cabeçalho de resposta rsct Opcional 2013-08-15 e posterior O Armazenamento do Azure define o Content-Type cabeçalho de resposta como o valor especificado no token SAS.

Especificar o campo de versão assinada

O campo obrigatório signedVersion (sv) especifica a versão do serviço para a assinatura de acesso compartilhado. Esse valor indica a versão do serviço que é usada para construir o signature campo e especifica a versão do serviço que manipula uma solicitação feita com essa assinatura de acesso compartilhado. O valor do sv campo deve ser a versão 2018-11-09 ou posterior.

Especificar o campo de recurso assinado

O campo obrigató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, contêiner ou diretório 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 está sempre dentro de um contêiner.

Especificar a duração da validade da assinatura

Os signedStart campos (st) e signedExpiry (se) indicam os tempos de início e expiração para a SAS. O campo signedExpiry é obrigató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 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 de usuário tiver expirado, a SAS falhará com um erro de autorização, independentemente de a PRÓPRIA SAS ainda ser válida.

Para obter mais informações sobre formatos UTC aceitos, consulte Formatar valores datetime.

Especificar as permissões

As permissões especificadas para o signedPermissions campo (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. Não é permitido especificar uma designação de permissão mais de uma vez.

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

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 em um novo blob.
Gravar w Contêiner
Diretório
Blob		 Tudo Criar ou gravar conteúdo, propriedades, metadados ou lista de bloqueios. Crie um instantâneo ou conceda o blob. Redimensionar o blob (blob da página somente). Use o blob como o destino de uma operação de cópia.
Excluir d Contêiner
Diretório
Blob		 Tudo Excluir um blob. Para a versão 2017-07-29 e posterior, a permissão Excluir também permite quebrar uma concessão em um blob. Para obter mais informações, consulte a operação De concessão de blob .
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 não recursivamente.
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. 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. 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 proprietário quando o chamador renomeia ou exclui 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.

Especificar um endereço IP ou intervalo de IP

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.

Quando você especifica um intervalo de endereços IP, 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 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 nesse cenário não deve incluir um endereço IP de saída para o signedIp campo. As solicitações que você faz de dentro da mesma região usando 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. As solicitações que você faz com a SAS devem ser originadas do endereço IP ou do intervalo de endereços especificados.
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. As solicitações que você faz com a SAS devem ser originadas do endereço IP ou do intervalo de endereços especificados.

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

O campo opcional signedProtocol (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 spr campo.

Especificar a ID do objeto assinado

O signedObjectId campo (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 no plataforma de identidade da Microsoft.

Especificar a ID do locatário assinado

O signedTenantId campo (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 Microsoft Entra no qual uma entidade de segurança é definida.

Especificar a hora de início da chave assinada

O campo opcional signedKeyStartTime (skt) 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. Se a hora de início for omitida, a hora de início da chave assinada será considerada a hora atual.

Especificar o tempo de expiração da chave assinada

O signedKeyExpiryTime campo (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 signedKeyService campo (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 de 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 signedkeyversion campo (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 signedkeyversion campo 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 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 Azure Data Lake Storage Gen2. Use um desses campos no token SAS para especificar a ID do objeto para uma entidade de segurança:

  • O saoid campo especifica a ID de objeto de uma entidade de segurança Microsoft Entra autorizada pelo proprietário da chave de delegação de usuário para 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 permissão adicional marcar em ACLs POSIX é executada.
  • O suoid campo especifica a ID do objeto de uma entidade de segurança Microsoft Entra quando um namespace hierárquico está habilitado para uma conta de armazenamento. O suoid campo é válido apenas para contas que têm um namespace hierárquico. Quando o suoid campo é incluído no token SAS, o Armazenamento do Azure executa uma ACL POSIX marcar na ID do objeto antes de autorizar a operação. Se esse marcar de ACL não for bem-sucedido, a operação falhará. Um namespace hierárquico deverá ser habilitado para a conta de armazenamento se o suoid campo estiver incluído no token SAS. Caso contrário, o marcar 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 necessário skoid . Para especificar uma ID de objeto no token SAS com o campo ou suoid , a entidade de segurança identificada no skoid campo 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.saoid Para obter mais informações sobre essas ações, consulte Operações do provedor de recursos do Azure.

Ao especificar a ID do saoid objeto no campo 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 skoid parâmetro .
  • Se o bit autoadesiva for 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 o 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 x-ms-owner cabeçalho for especificado, o valor especificado pela ID do objeto deverá corresponder ao valor especificado pelo x-ms-owner cabeçalho.
  • Se uma operação definir o grupo para um diretório ou blob e o x-ms-group cabeçalho for especificado, o valor especificado pela ID do objeto deverá ser um membro do grupo especificado pelo x-ms-group cabeçalho.
  • Se uma operação definir as permissões ou a ACL para um diretório ou blob, uma das duas condições a seguir 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 signedPermissions campo (sp) deve incluir a Ownership permissão (o) além da Permissions permissão (p).

A ID do objeto especificada no saoid campo ou suoid é incluída nos logs de diagnóstico quando você faz solicitações usando o token SAS.

O saoid campo ou suoid só terá suporte se o signedVersion campo (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 signedCorrelationId campo (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 na versão 2020-02-10 e posterior.

Especificar a profundidade do diretório

Se o signedResource campo especificar um diretório (sr=d), você também deverá 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 e posterior.

Especificar parâmetros de consulta para substituir cabeçalhos de resposta

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. 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 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 um token SAS, o cabeçalho de Content-Type resposta será definido binarycomo . Esse valor substitui o valor do cabeçalho Content-Type armazenado para o blob para uma solicitação usando somente 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 na cadeia de caracteres para sinal usada 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 signed encryption scope campo (ses) especifica um escopo de criptografia que o aplicativo cliente usa quando você carrega blobs usando o token SAS por meio da operação Put Blob . O signed encryption scope campo tem suporte quando o campo de versão assinada (sv) no token SAS é 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 ses campo 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).

Se o x-ms-encryption-scope cabeçalho e o ses parâmetro de consulta 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 signature campo (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 construída a partir dos campos que devem ser verificados para autorizar a solicitação. A assinatura é um HMAC que é calculado sobre a cadeia de caracteres para assinar e a chave usando o algoritmo SHA256 e, em seguida, 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, em seguida, compute a assinatura usando o algoritmo HMAC-SHA256. Os campos incluídos na cadeia de caracteres a assinar devem ser decodificados por URL.

Os campos 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 de 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 sdd parâmetro .

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 canonicalizedResource parte 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 Gen2)
URL = https://myaccount.dfs.core.windows.net/music  
canonicalizedResource = "/blob/myaccount/music"
Exemplo de diretório (Azure Data Lake Storage Gen2)
URL = https://myaccount.dfs.core.windows.net/music/instruments/guitar/  
canonicalizedResource = "/blob/myaccount/music/instruments/guitar/"
Exemplo de blob (Azure Data Lake Storage Gen2)
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. Inclua o caractere de nova linha (\n) depois da 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=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.
ID de objeto skoid=<object-id> Uma entidade de segurança Microsoft Entra.
ID do locatário sktid=<tenant-id> O Microsoft Entra locatário em que 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 que foi usada para obter a chave de delegação do usuário.
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 serviço Blob sv=2022-11-02 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 que é calculado em uma cadeia de caracteres para assinar e chave usando o algoritmo SHA256 e, em seguida, 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 de usuário ou alterando ou removendo atribuições de função RBAC para a entidade de segurança usada para criar a SAS.

Importante

A chave de delegação de usuário e 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 de usuário

Você pode revogar a chave de delegação de usuário chamando a operação Revogar Chaves de Delegação de Usuário . Quando você revoga a chave de delegação de usuário, todas as assinaturas de acesso compartilhado que dependem dessa chave se tornam inválidas. Em seguida, você pode chamar a operação Obter Chave de Delegação de Usuário novamente e usar a chave para criar novas assinaturas de acesso compartilhado. Essa é a maneira mais rápida de revogar uma SAS de delegação de usuário.

Alterar ou remover atribuições de função

Você pode alterar ou remover a atribuição de função RBAC 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.

Confira também