Criar uma SAS de serviço para um contêiner ou blob com .NET

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.

Este artigo mostra como usar a chave da conta de armazenamento para criar uma SAS de serviço para um contêiner ou blob com a biblioteca de clientes do Armazenamento de Blobs do Azure para .NET.

Sobre a SAS de serviço

Uma SAS de serviço é assinada com a chave de acesso da conta. Você pode usar a classe StorageSharedKeyCredential para criar a credencial usada para assinar a SAS de serviço.

Você também pode usar uma política de acesso armazenada para definir as permissões e a duração da SAS. Se o nome de uma política de acesso armazenada existente for fornecido, essa política está associada com a SAS. Para saber mais sobre as políticas de acesso armazenadas, veja Definir uma política de acesso armazenada. Se nenhuma política de acesso armazenada for fornecida, os exemplos de código neste artigo mostrarão como definir permissões e duração para a SAS.

Criar uma SAS de serviço

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

public static async Task<Uri> CreateServiceSASContainer(
    BlobContainerClient containerClient,
    string storedPolicyName = null)
{
    // Check if BlobContainerClient object has been authorized with Shared Key
    if (containerClient.CanGenerateSasUri)
    {
        // Create a SAS token that's valid for one day
        BlobSasBuilder sasBuilder = new BlobSasBuilder()
        {
            BlobContainerName = containerClient.Name,
            Resource = "c"
        };

        if (storedPolicyName == null)
        {
            sasBuilder.ExpiresOn = DateTimeOffset.UtcNow.AddDays(1);
            sasBuilder.SetPermissions(BlobContainerSasPermissions.Read);
        }
        else
        {
            sasBuilder.Identifier = storedPolicyName;
        }

        Uri sasURI = containerClient.GenerateSasUri(sasBuilder);

        return sasURI;
    }
    else
    {
        // Client object is not authorized via Shared Key
        return null;
    }
}

public static async Task<Uri> CreateServiceSASBlob(
    BlobClient blobClient,
    string storedPolicyName = null)
{
    // Check if BlobContainerClient object has been authorized with Shared Key
    if (blobClient.CanGenerateSasUri)
    {
        // Create a SAS token that's valid for one day
        BlobSasBuilder sasBuilder = new BlobSasBuilder()
        {
            BlobContainerName = blobClient.GetParentBlobContainerClient().Name,
            BlobName = blobClient.Name,
            Resource = "b"
        };

        if (storedPolicyName == null)
        {
            sasBuilder.ExpiresOn = DateTimeOffset.UtcNow.AddDays(1);
            sasBuilder.SetPermissions(BlobContainerSasPermissions.Read);
        }
        else
        {
            sasBuilder.Identifier = storedPolicyName;
        }

        Uri sasURI = blobClient.GenerateSasUri(sasBuilder);

        return sasURI;
    }
    else
    {
        // Client object is not authorized via Shared Key
        return null;
    }
}

Usar uma SAS de serviço para autorizar um objeto cliente

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

string accountName = "<storage-account-name>";
string accountKey = "<storage-account-key";
StorageSharedKeyCredential storageSharedKeyCredential =
    new(accountName, accountKey);
BlobServiceClient blobServiceClient = new BlobServiceClient(
    new Uri($"https://{accountName}.blob.core.windows.net"),
    storageSharedKeyCredential);

// Create a Uri object with a service SAS appended
BlobContainerClient containerClient = blobServiceClient
    .GetBlobContainerClient("sample-container");
Uri containerSASURI = await CreateServiceSASContainer(containerClient);

// Create a container client object representing 'sample-container' with SAS authorization
BlobContainerClient containerClientSAS = new BlobContainerClient(containerSASURI);

string accountName = "<storage-account-name>";
string accountKey = "<storage-account-key";
StorageSharedKeyCredential storageSharedKeyCredential =
    new(accountName, accountKey);
BlobServiceClient blobServiceClient = new BlobServiceClient(
    new Uri($"https://{accountName}.blob.core.windows.net"),
    storageSharedKeyCredential);

// Create a Uri object with a service SAS appended
BlobClient blobClient = blobServiceClient
    .GetBlobContainerClient("sample-container")
    .GetBlobClient("sample-blob.txt");
Uri blobSASURI = await CreateServiceSASBlob(blobClient);

// Create a blob client object representing 'sample-blob.txt' with SAS authorization
BlobClient blobClientSAS = new BlobClient(blobSASURI);

Definir uma política de acesso armazenada

Uma política de acesso armazenada fornece um nível de controle adicional sobre uma assinatura de acesso compartilhado (SAS) no nível de serviço no lado do servidor. Estabelecer uma política de acesso armazenada serve para agrupar assinaturas de acesso compartilhado e fornecer restrições adicionais para assinaturas que são associadas pela política.

Você pode usar uma política de acesso armazenada para alterar a hora de início, a hora de expiração ou as permissões de uma assinatura. Você também pode usar uma política de acesso armazenada para revogar uma assinatura após a sua emissão. Esta seção se concentra em contêineres de blob, mas também há suporte para políticas de acesso armazenada para compartilhamentos de arquivos, filas e tabelas.

Para gerenciar políticas de acesso armazenadas em um recurso de contêiner, chame um dos seguintes métodos de um objeto BlobContainerClient:

• SetAccessPolicy
• SetAccessPolicyAsync

Criar ou modificar uma política de acesso armazenada

Você pode definir no máximo cinco políticas de acesso em um recurso de cada vez. Cada campo SignedIdentifier, com seu campo Id exclusivo, corresponde a uma política de acesso. Tentar definir mais de cinco políticas de acesso ao mesmo tempo faz com que o serviço retorne o código de status 400 (Bad Request).

O exemplo de código a seguir mostra como criar duas políticas de acesso armazenadas em um recurso de contêiner:

public static async Task CreateStoredAccessPolicyAsync(BlobContainerClient containerClient)
{
    // Create a stored access policy with read and write permissions, valid for one day
    List<BlobSignedIdentifier> signedIdentifiers = new List<BlobSignedIdentifier>
    {
        new BlobSignedIdentifier
        {
            Id = "sample-read-write-policy",
            AccessPolicy = new BlobAccessPolicy
            {
                StartsOn = DateTimeOffset.UtcNow,
                ExpiresOn = DateTimeOffset.UtcNow.AddDays(1),
                Permissions = "rw"
            }
        },
        new BlobSignedIdentifier
        {
            Id = "sample-read-policy",
            AccessPolicy = new BlobAccessPolicy
            {
                StartsOn = DateTimeOffset.UtcNow,
                ExpiresOn = DateTimeOffset.UtcNow.AddDays(1),
                Permissions = "r"
            }
        }
    };

    // Set the container's access policy
    await containerClient.SetAccessPolicyAsync(permissions: signedIdentifiers);
}

Você também pode modificar uma política existente. O exemplo de código a seguir mostra como modificar uma única política de acesso armazenada para atualizar a data de validade da política:

public static async Task ModifyStoredAccessPolicyAsync(BlobContainerClient containerClient)
{
    BlobContainerAccessPolicy accessPolicy = await containerClient.GetAccessPolicyAsync();
    List<BlobSignedIdentifier> signedIdentifiers = accessPolicy.SignedIdentifiers.ToList();

    // Modify the expiration date a single policy
    var samplePolicy = signedIdentifiers.FirstOrDefault(item => item.Id == "sample-read-policy");
    samplePolicy.AccessPolicy.PolicyExpiresOn = DateTimeOffset.UtcNow.AddDays(7);

    // Update the container's access policy
    await containerClient.SetAccessPolicyAsync(permissions: signedIdentifiers);
}

Revogar ou excluir uma política de acesso armazenada

Para revogar uma política de acesso armazenado, a Microsoft recomenda excluir o identificador assinado e fazer um novo. A alteração do identificador assinado interrompe as associações entre todas as assinaturas existentes e a política de acesso armazenada. A exclusão ou modificação da política de acesso armazenada afeta imediatamente todas as assinaturas de acesso compartilhadas associadas a ela.

O exemplo de código a seguir mostra como revogar uma política alterando a propriedade Id do identificador assinado. Essa abordagem exclui efetivamente o identificador assinado e faz um novo:

public static async Task RevokeStoredAccessPolicyAsync(BlobContainerClient containerClient)
{
    BlobContainerAccessPolicy accessPolicy = await containerClient.GetAccessPolicyAsync();
    List<BlobSignedIdentifier> signedIdentifiers = accessPolicy.SignedIdentifiers.ToList();

    // Revoke a single policy by changing its name
    var samplePolicy = signedIdentifiers.FirstOrDefault(item => item.Id == "sample-read-policy");
    samplePolicy.Id = "sample-read-policy-revoke";

    // Update the container's access policy
    await containerClient.SetAccessPolicyAsync(permissions: signedIdentifiers);
}

Você também pode remover todas as políticas de acesso de um recurso de contêiner chamando SetAccessPolicyAsync com um parâmetro permissions vazio. O exemplo a seguir mostra como excluir todas as políticas de acesso armazenadas de um contêiner especificado:

public static async Task DeleteStoredAccessPolicyAsync(BlobContainerClient containerClient)
{
    // Remove all stored access policies for the container resource
    await containerClient.SetAccessPolicyAsync();
}

Recursos

Para saber mais sobre como criar um SAS de serviço usando a biblioteca de clientes do Armazenamento de Blobs do Azure para o .NET, consulte os recursos a seguir.

Exemplos de código

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

Recursos da biblioteca de clientes

• Documentação de referência da biblioteca de clientes
• Código-fonte da biblioteca de clientes
• Pacote (NuGet)

Confira também

• Conceder acesso limitado aos recursos de Armazenamento do Azure usando as SAS (assinaturas de acesso compartilhado)
• Criar uma SAS de serviço