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

Uma assinatura de acesso compartilhado (SAS) permite que você conceda acesso limitado a contêineres e blobs em sua conta de armazenamento. Ao criar uma SAS, você especifica suas restrições, incluindo quais recursos do Armazenamento do Azure um cliente tem permissão para acessar, quais permissões eles têm nesses recursos e por quanto tempo a SAS é válida.

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

• Com uma chave criada usando credenciais do Microsoft Entra. Uma SAS assinada com credenciais do Microsoft Entra é uma SAS de delegação de usuário. Um cliente que cria uma SAS de delegação de usuário deve receber 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 a 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. O cliente que cria uma SAS de serviço deve ter acesso direto à chave da conta ou receber a permissão Microsoft.Storage/storageAccounts/listkeys/action . Para saber mais, consulte Criar uma SAS de serviço ou Criar uma SAS de conta.

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 usando a biblioteca de cliente do Armazenamento do 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 credenciais do Microsoft Entra é chamada de SAS de delegação de usuário, porque o token 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 prática recomendada de segurança, em vez de usar a chave da conta, que pode ser comprometida mais facilmente. 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 a SAS de delegação de usuário, consulte Criar uma SAS de delegação de usuário.

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

Atribuir funções do Azure para acesso a dados

Quando uma entidade de segurança do Microsoft Entra tenta acessar dados, essa entidade de segurança deve ter permissões para o recurso. Quer a entidade de segurança seja uma identidade gerenciada no Azure ou uma conta de usuário do Microsoft Entra executando código no ambiente de desenvolvimento, a entidade de segurança deve receber uma função do Azure que conceda acesso aos dados. Para obter informações sobre como atribuir permissões por meio do RBAC do Azure, consulte Atribuir uma função do Azure para acesso a dados de blob.

Configure 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 usando pip install:

pip install azure-storage-blob azure-identity

Configurar o código do aplicativo

Aditar as seguintes import diretivas:

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 autenticada

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

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

# 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 a partir de seus aplicativos com o SDK do Python, consulte Autenticar aplicativos Python nos serviços do Azure.

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

Cada SAS é assinado 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 depende de suas credenciais do Microsoft Entra. Quando um cliente solicita uma chave de delegação de usuário usando um token OAuth 2.0, o Armazenamento de Blob retorna a chave de delegação do usuário em nome do usuário.

Depois de ter a chave de delegação do usuário, você pode usar essa chave 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 usado para adquiri-la, portanto, o token não precisa ser renovado se a chave ainda for válida. Você pode especificar o período de tempo em que a chave permanece válida, até um máximo de sete dias.

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

• get_user_delegation_key

O exemplo de código a seguir mostra como solicitar a chave de delegação do 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 utilizador

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

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

def create_user_delegation_sas_blob(self, blob_client: BlobClient, 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_blob_sas(
        account_name=blob_client.account_name,
        container_name=blob_client.container_name,
        blob_name=blob_client.blob_name,
        user_delegation_key=user_delegation_key,
        permission=BlobSasPermissions(read=True),
        expiry=expiry_time,
        start=start_time
    )

    return sas_token

Usar uma SAS de delegação de usuário para autorizar um objeto 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.

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

# 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"{blob_client.url}?{sas_token}"

# Create a BlobClient object with SAS authorization
blob_client_sas = BlobClient.from_blob_url(blob_url=sas_url)

Recursos

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

Amostras de código

• Exibir exemplos de código deste artigo (GitHub)

Operações da API REST

O SDK do Azure para Python contém bibliotecas que se baseiam na API REST do Azure, permitindo que você interaja com operações da API REST por meio de paradigmas Python familiares. O método de biblioteca de cliente para obter uma chave de delegação de usuário usa as seguintes operações de API REST:

• Obter chave de delegação de usuário (API REST)

Recursos da biblioteca do cliente

• Documentação de referência da biblioteca cliente
• Código fonte da biblioteca cliente
• Pacote (PyPi)

Consulte também

• Conceder acesso limitado aos recursos do Armazenamento do Azure com assinaturas de acesso partilhado (SAS)
• Crie uma SAS de delegação de utilizador

Conteúdos relacionados

• Este artigo faz parte do guia do desenvolvedor do Blob Storage para Python. Para saber mais, consulte a lista completa de artigos do guia do desenvolvedor em Build your Python app.