Criar uma SAS de serviço para um blob com .NET

  • Artigo

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.

Nota

Uma SAS de delegação de usuário oferece segurança superior a uma SAS assinada com a chave da conta de armazenamento. A Microsoft recomenda o uso de uma SAS de delegação de usuário quando possível. Para obter mais informações, consulte Conceder acesso limitado a dados com assinaturas de acesso compartilhado (SAS).

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

Sobre o serviço SAS

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 armazenado para definir as permissões e a duração do SAS. Se o nome de uma política de acesso armazenado existente for fornecido, essa política será associada à SAS. Para saber mais sobre políticas de acesso armazenado, consulte Definir uma política de acesso armazenado. Se nenhuma política de acesso armazenado for fornecida, os exemplos de código neste artigo mostram como definir permissões e duração para o SAS.

Criar uma SAS de serviço para um blob

O exemplo de código a seguir mostra como criar uma SAS de serviço para um recurso de blob. Primeiro, o código verifica se o objeto BlobClient está autorizado com uma credencial de chave compartilhada verificando a propriedade CanGenerateSasUri . Em seguida, ele gera o serviço SAS por meio da classe BlobSasBuilder e chama GenerateSasUri para criar um URI SAS de serviço com base nos objetos cliente e construtor.

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 de cliente

O exemplo de código a seguir mostra como usar o serviço SAS para autorizar um objeto BlobClient . Este objeto de cliente pode ser usado para executar operações no recurso de blob com base nas permissões concedidas pelo SAS.

Primeiro, crie um objeto BlobServiceClient assinado com a chave de acesso da conta:

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

Em seguida, gere o serviço SAS como mostrado no exemplo anterior e use o SAS para autorizar um objeto BlobClient :

// 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 armazenado fornece um nível adicional de controle sobre uma assinatura de acesso compartilhado (SAS) de nível de serviço no lado do servidor. O estabelecimento de uma política de acesso armazenado serve para agrupar assinaturas de acesso compartilhado e fornecer restrições adicionais para assinaturas vinculadas à política.

Você pode usar uma política de acesso armazenado 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 armazenado para revogar uma assinatura depois que ela for emitida. Esta seção se concentra em contêineres de blob, mas as políticas de acesso armazenado também são suportadas para compartilhamentos de arquivos, filas e tabelas.

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

Criar ou modificar uma política de acesso armazenado

Você pode definir um máximo de cinco políticas de acesso em um recurso de cada vez. Cada SignedIdentifier campo, com o seu campo único Id , 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 400 (Bad Request)de status .

O exemplo de código a seguir mostra como criar duas políticas de acesso armazenado 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 armazenado para atualizar a data de expiração 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, você pode excluí-la, renomeá-la alterando o identificador assinado ou alterar o tempo de expiração para um valor no passado. A alteração do identificador assinado quebra as associações entre quaisquer assinaturas existentes e a política de acesso armazenada. Alterar o tempo de expiração para um valor no passado faz com que todas as assinaturas associadas expirem. A exclusão ou modificação da política de acesso armazenado afeta imediatamente todas as assinaturas de acesso compartilhado associadas a ela.

O exemplo de código a seguir mostra como revogar uma política alterando a Id propriedade para o identificador assinado:

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 vazio permissions . 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 uma SAS de serviço usando a biblioteca de cliente do Armazenamento de Blobs do Azure para .NET, consulte os recursos a seguir.

Recursos da biblioteca do cliente

Consulte também