Compartilhar via

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

  • 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 por meio da Biblioteca de clientes do Armazenamento do Microsoft Azure para Python.

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

Atribuir funções do Azure para acesso aos dados

Quando uma entidade de segurança do Microsoft Entra tenta acessar dados, ela precisa ter permissões para o recurso. Se a entidade de segurança for uma identidade gerenciada no Azure ou uma conta de usuário do Microsoft Entra executando código no ambiente de desenvolvimento, ela deverá receber uma função do Azure que conceda acesso aos dados. Para saber mais sobre como atribuir permissões pelo RBAC do Azure, confira Atribuir uma função do Azure para acesso a dados de blob.

Configurar o seu projeto

Para trabalhar com os exemplos de código neste artigo, siga estas etapas para configurar seu projeto.

Instalar Pacotes

Instale os seguintes pacotes por meio de pip install:

pip install azure-storage-blob azure-identity

Configurar o código do aplicativo

Adicione as seguintes diretivas import:

from azure.identity import DefaultAzureCredential
from azure.storage.blob import (
    BlobServiceClient,
    ContainerClient,
    BlobClient,
    BlobSasPermissions,
    ContainerSasPermissions,
    UserDelegationKey,
    generate_container_sas,
    generate_blob_sas
)

Obter uma credencial de token autenticado

Para obter uma credencial de token que seu código possa usar para autorizar solicitações ao Armazenamento de Blobs do Azure, crie uma instância da classe DefaultAzureCredential. Para obter mais informações sobre como usar a classe DefaultAzureCredential para autorizar uma identidade gerenciada a acessar o Armazenamento de Blobs, consulte Biblioteca do cliente do Azure Identity para Python.

O trecho de código a seguir mostra como obter a credencial de token autenticado e usá-la para criar um cliente de serviço para o armazenamento de blobs:

# Construct the blob endpoint from the account name
account_url = "https://<storage-account-name>.blob.core.windows.net"

#Create a BlobServiceClient object using DefaultAzureCredential
blob_service_client = BlobServiceClient(account_url, credential=DefaultAzureCredential())

Para saber mais sobre como autorizar o acesso ao Armazenamento de Blobs dos seus aplicativos com o SDK do Python consulte Como autenticar aplicativos Python com os serviços do Azure.

Obter a chave de delegação do usuário

Cada SAS é assinada com uma chave. Para criar uma SAS de delegação de usuário, você deve primeiro solicitar uma chave de delegação de usuário, que é usada 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 se baseia em suas credenciais do Microsoft Entra. Quando um cliente solicita uma chave para delegação de usuários usando um token OAuth 2.0, o Armazenamento de Blobs do Azure retorna a chave para delegação de usuários em nome do usuário.

Depois de ter a chave de delegação do usuário, você pode usar essa chave para criar algumas assinaturas de acesso compartilhado de delegação de usuário, durante o tempo de vida da chave. A chave de delegação do usuário é independente do token OAuth 2.0 usado para adquiri-la, portanto, o token não precisará ser renovado se a chave ainda estiver válida. Você pode especificar o período de tempo em que a chave permanece válida de até no máximo sete dias.

Use um dos seguintes métodos para solicitar a chave de delegação do usuário:

O exemplo de código a seguir mostra como solicitar a chave de delegação de usuário:

def request_user_delegation_key(self, blob_service_client: BlobServiceClient) -> UserDelegationKey:
    # Get a user delegation key that's valid for 1 day
    delegation_key_start_time = datetime.datetime.now(datetime.timezone.utc)
    delegation_key_expiry_time = delegation_key_start_time + datetime.timedelta(days=1)

    user_delegation_key = blob_service_client.get_user_delegation_key(
        key_start_time=delegation_key_start_time,
        key_expiry_time=delegation_key_expiry_time
    )

    return user_delegation_key

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

Você pode criar uma SAS de delegação de usuário para um contêiner ou blob, com base nas necessidades do seu aplicativo.

Depois de obter a chave de delegação de usuário, você pode criar uma SAS de delegação de usuário. Você pode criar uma SAS de delegação de usuário para delegar acesso limitado a um recurso de contêiner usando o seguinte método:

A chave de delegação de usuário para assinar a SAS é passada para o método como o argumento user_delegation_key. As permissões permitidas são passadas para o método como o argumento permission e são definidas na classe ContainerSasPermissions.

O exemplo de código a seguir mostra como criar uma SAS de delegação de usuário para um contêiner:

def create_user_delegation_sas_container(self, container_client: ContainerClient, user_delegation_key: UserDelegationKey):
    # Create a SAS token that's valid for one day, as an example
    start_time = datetime.datetime.now(datetime.timezone.utc)
    expiry_time = start_time + datetime.timedelta(days=1)

    sas_token = generate_container_sas(
        account_name=container_client.account_name,
        container_name=container_client.container_name,
        user_delegation_key=user_delegation_key,
        permission=ContainerSasPermissions(read=True),
        expiry=expiry_time,
        start=start_time
    )

    return sas_token

Usar uma SAS de delegação de usuário para autorizar um objeto de cliente

Você pode usar uma SAS de delegação de usuário para autorizar um objeto cliente a executar operações em um contêiner ou blob com base nas permissões concedidas pela SAS.

O exemplo de código a seguir mostra como usar a SAS de delegação de usuário criada no exemplo anterior para autorizar um objeto ContainerClient. Esse objeto cliente pode ser usado para executar operações no recurso de contêiner com base nas permissões concedidas pela SAS.

# The SAS token string can be appended to the resource URL with a ? delimiter
# or passed as the credential argument to the client constructor
sas_url = f"{container_client.url}?{sas_token}"

# Create a ContainerClient object with SAS authorization
container_client_sas = ContainerClient.from_container_url(container_url=sas_url)

Recursos

Para saber mais sobre como criar uma SAS de delegação de usuário usando a biblioteca de clientes do Armazenamento de Blobs do Azure para Python, consulte os recursos a seguir.

Exemplos de código

Operações da API REST

O SDK do Azure para Python contém bibliotecas que criam sobre a API REST do Azure, permitindo a interação com as operações de API REST por meio de paradigmas conhecidos do Python. O método da biblioteca de clientes para obter uma chave de delegação de usuário usa as seguintes operações da API REST:

Recursos da biblioteca de clientes

Confira também

Conteúdo relacionado

  • Este artigo faz parte do guia para desenvolvedores do Armazenamento de Blobs para Python. Para saber mais, veja a lista completa de artigos do guia do desenvolvedor em Criar seu aplicativo Python.