Criar uma SAS de delegação de usuário para um contêiner ou blob com o PowerShell

  • Artigo

Uma SAS (Assinatura de Acesso Compartilhado) permite conceder acesso limitado a contêineres e blobs da conta de armazenamento. Ao criar uma SAS, você especificará suas restrições, inclusive que recursos do Armazenamento do Azure um cliente terá permissão para acessar, que permissões ele terá nesses recursos e por quanto tempo a SAS é válida.

Cada SAS é assinada com uma chave. Você pode assinar uma SAS de uma das duas maneiras:

  • Com uma chave criada utilizando as credenciais do Microsoft Entra. Uma SAS assinada com credenciais do Microsoft Entra é uma SAS de delegação de usuário. É necessário atribuir um cliente que cria uma SAS de delegação de usuário a uma função RBAC do Azure que inclua a ação Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey. Para saber mais, consulte Criar uma SAS de delegação de usuário.
  • Com uma chave da conta de armazenamento. Tanto uma SAS de serviço quanto uma SAS de conta são assinadas com a chave da conta de armazenamento. É necessário que o cliente que cria uma SAS de serviço tenha acesso direto à chave da conta ou receba a permissão Microsoft.Storage/storageAccounts/listkeys/action. Para saber mais, consulte Criar uma SAS de serviço ou Criar uma SAS de conta.

Observação

Uma SAS de delegação de usuário oferece mais segurança do que uma SAS que é assinada com a chave da conta de armazenamento. A Microsoft recomenda usar uma SAS de delegação de usuário quando possível. Para saber mais, confira Conceder acesso limitado a dados com assinaturas de acesso compartilhado (SAS).

Este artigo mostra como usar as credenciais do Microsoft Entra para criar uma SAS de delegação de usuário para um contêiner ou blob com o Azure PowerShell.

Sobre a delegação de usuários SAS

Um token SAS para acesso a um contêiner ou blob pode ser protegido usando credenciais do Microsoft Entra ou uma chave de conta. Uma SAS protegida com as credenciais do Microsoft Entra é chamada de SAS de delegação de usuário, pois o token do OAuth 2.0 usado para assinar a SAS é solicitado em nome do usuário.

A Microsoft recomenda que você use as credenciais do Microsoft Entra quando possível como uma melhor prática de segurança, em vez de usar a 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 segurança superior. Para obter mais informações sobre o SAS de delegação de usuário, consulte Criar um SAS de delegação de usuário.

Cuidado

Qualquer cliente que possua um SAS válido pode acessar os dados em sua conta de armazenamento conforme permitido por esse SAS. É 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.

Para obter mais informações sobre assinaturas de acesso compartilhado, confira Conceder acesso limitado a recursos de Armazenamento do Azure usando SAS (assinaturas de acesso compartilhado).

Instalar o módulo do PowerShell

Para criar uma SAS de delegação de usuário com o PowerShell, instale a versão 1.10.0 ou mais recente do módulo Az.Storage. Siga estas etapas para instalar a versão mais recente do módulo:

  1. Desinstale as instalações anteriores do Azure PowerShell:

    • Remova as instalações anteriores do Azure PowerShell do Windows usando a configuração Aplicativos e recursos em Configurações.
    • Remova todos os módulos do Azure de %Program Files%\WindowsPowerShell\Modules.

  2. Verifique se tem a versão mais recente do PowerShellGet instalado. Abra uma janela do Windows PowerShell e execute o seguinte comando para instalar a versão mais recente:

    Install-Module PowerShellGet -Repository PSGallery -Force

  3. Feche e reabra a janela do PowerShell depois de instalar o PowerShellGet.

  4. Instale a versão mais recente do Azure PowerShell:

    Install-Module Az -Repository PSGallery -AllowClobber

  5. Certifique-se de instalar o Azure PowerShell versão 3.2.0 ou mais recente. Execute o comando a seguir para instalar a versão mais recente do módulo do PowerShell para o Armazenamento do Azure:

    Install-Module -Name Az.Storage -Repository PSGallery -Force

  6. Feche e reabra a janela do PowerShell.

Para verificar qual versão do módulo Az.Storage está instalada, execute o seguinte comando:

Get-Module -ListAvailable -Name Az.Storage -Refresh

Para obter mais informações sobre como instalar o Azure PowerShell, consulte Instalar o Azure PowerShell com o PowerShellGet.

Entrar no Azure PowerShell com a ID do Microsoft Entra

Chame o comando Connect-AzAccount para entrar com sua conta do Microsoft Entra:

Connect-AzAccount

Para obter mais informações sobre como se conectar com o PowerShell, consulte Conectar-se com o Azure PowerShell.

Atribuir permissões com o RBAC do Azure

Para criar uma SAS de delegação de usuário do Azure PowerShell, a conta do Microsoft Entra usada para entrar no PowerShell deve receber uma função que inclua a ação Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey. Essa permissão permite que a conta do Microsoft Entra solicite a chave de delegação do usuário. Essa chave é usada para assinar a SAS de delegação de usuário. A função que fornece a ação Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey deve ser atribuída no nível da conta de armazenamento, do grupo de recursos ou da assinatura. Você pode saber mais sobre as permissões de RBAC do Azure para a criação de uma SAS de delegação de usuário na seção Atribuir permissões com o RBAC do Azure em Criar uma SAS de delegação de usuário.

Se você não tiver permissões suficientes para atribuir funções do Azure a uma entidade de segurança do Microsoft Entra, talvez seja necessário solicitar ao proprietário ou administrador da conta que atribua as permissões necessárias.

O exemplo a seguir atribui a função de colaborador de dados de blob de armazenamento, que inclui a ação Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey. A função tem o escopo no nível da conta de armazenamento.

Lembre-se de substituir os valores dos espaços reservados entre colchetes angulares pelos seus próprios valores:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Storage Blob Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account>"

Para saber mais sobre as funções internas que incluem a ação Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey, consulte Funções internas do Azure.

Usar as credenciais do Microsoft Entra para proteger uma SAS

Quando uma SAS de delegação de usuário é criada com o Azure PowerShell, a chave de delegação de usuário usada para assiná-la é criada implicitamente. A hora de início e a hora de expiração especificadas para a SAS também são usadas como a hora de início e a hora de expiração da chave de delegação de usuário.

Como o intervalo máximo de validade da chave de delegação de usuário é de sete dias a partir da data de início, você deve especificar uma hora de expiração para a SAS que esteja dentro desse período. Como a chave de delegação de usuário expira em sete dias e invalida a SAS depois disso, mesmo que uma SAS tenha o tempo de expiração superior a sete dias, ela ainda terá validade apenas durante esse período.

Para criar uma SAS de delegação de usuário para um contêiner ou blob com o Azure PowerShell, primeiro crie um novo objeto de contexto do Armazenamento do Azure especificando o parâmetro -UseConnectedAccount. O parâmetro -UseConnectedAccount especifica que o comando cria o objeto de contexto na conta do Microsoft Entra com a qual você entrou.

Lembre-se de substituir os valores dos espaços reservados entre colchetes angulares pelos seus próprios valores:

$ctx = New-AzStorageContext -StorageAccountName <storage-account> -UseConnectedAccount

Criar uma SAS de delegação de usuário para um contêiner

Para retornar um token SAS de delegação de usuário para um contêiner, chame o comando New-AzStorageContainerSASToken transmitindo o objeto de contexto do Armazenamento do Azure criado anteriormente.

O exemplo a seguir retorna um token SAS de delegação de usuário para um contêiner. Lembre-se de substituir os valores de espaço reservado entre colchetes pelos seus:

New-AzStorageContainerSASToken -Context $ctx `
    -Name <container> `
    -Permission racwdl `
    -ExpiryTime <date-time>

O token SAS de delegação de usuário retornado será semelhante ao seguinte:

?sv=2018-11-09&sr=c&sig=<sig>&skoid=<skoid>&sktid=<sktid>&skt=2019-08-05T22%3A24%3A36Z&ske=2019-08-07T07%3A
00%3A00Z&sks=b&skv=2018-11-09&se=2019-08-07T07%3A00%3A00Z&sp=rwdl

Criar uma SAS de delegação de usuário para um blob

Para retornar um token SAS de delegação de usuário para um blob, chame o comando New-AzStorageBlobSASToken transmitindo o objeto de contexto do Armazenamento do Azure criado anteriormente.

A sintaxe a seguir retorna uma SAS de delegação de usuário para um blob. O exemplo especifica o parâmetro -FullUri, que retorna o URI do blob com o token SAS anexado. Lembre-se de substituir os valores de espaço reservado entre colchetes pelos seus:

New-AzStorageBlobSASToken -Context $ctx `
    -Container <container> `
    -Blob <blob> `
    -Permission racwd `
    -ExpiryTime <date-time>
    -FullUri

O token SAS de delegação de usuário retornado será semelhante ao seguinte:

https://storagesamples.blob.core.windows.net/sample-container/blob1.txt?sv=2018-11-09&sr=b&sig=<sig>&skoid=<skoid>&sktid=<sktid>&skt=2019-08-06T21%3A16%3A54Z&ske=2019-08-07T07%3A00%3A00Z&sks=b&skv=2018-11-09&se=2019-08-07T07%3A00%3A00Z&sp=racwd

Observação

Uma SAS de delegação de usuário não dá suporte à definição de permissões com uma política de acesso armazenada.

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

Para revogar uma SAS de delegação de usuário com o Azure PowerShell, chame o comando Revoke-AzStorageAccountUserDelegationKeys. Esse comando revoga todas as chaves de delegação de usuário associadas à conta de armazenamento especificada. Todas as assinaturas de acesso compartilhado associadas a essas chaves são invalidadas.

Lembre-se de substituir os valores dos espaços reservados entre colchetes angulares pelos seus próprios valores:

Revoke-AzStorageAccountUserDelegationKeys -ResourceGroupName <resource-group> `
    -StorageAccountName <storage-account>

Importante

Tanto a chave de delegação de usuário quanto as atribuições de função do Azure são armazenadas em cache pelo Armazenamento do Azure. Por isso, pode haver um atraso entre a inicialização do processo de revogação e a invalidação de uma SAS de delegação de usuário existente.

Próximas etapas