Creare una firma di accesso condiviso del servizio per un contenitore o un BLOB con .NET

  • Articolo

Una firma di accesso condiviso (SAS) permette all'utente di concedere l'accesso limitato a contenitori e BLOB nell'account di archiviazione. Quando si crea una firma di accesso condiviso, si specificano i relativi vincoli, incluse le risorse di Archiviazione di Azure alle quali un client è autorizzato ad accedere, le autorizzazioni di cui dispone per tali risorse e la durata della validità della firma di accesso condiviso.

Ogni firma di accesso condiviso viene firmata con una chiave. Questa operazione può essere eseguita in due modi:

  • Con una chiave creata utilizzando le credenziali di Microsoft Entra. Una firma di accesso condiviso firmata con le credenziali di Microsoft Entra è una firma di accesso condiviso di delega utente. A un client che crea una firma di accesso condiviso di delega utente deve essere assegnato un ruolo di Controllo degli accessi in base al ruolo di Azure che include l'azione Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey. Per altre informazioni, vedere Creare una firma di accesso condiviso di delega utente.
  • Con la chiave dell'account di archiviazione. Una firma di accesso condiviso del servizio e una firma di accesso condiviso dell'account, vengono entrambe firmate con la chiave dell'account di archiviazione. Il client che crea una firma di accesso condiviso del servizio deve avere accesso diretto alla chiave dell'account o disporre dell'autorizzazione Microsoft.Storage/storageAccounts/listkeys/action. Per altre informazioni, vedere Creare una firma di accesso condiviso del servizio oppure Creare una firma di accesso condiviso dell'account.

Nota

Una firma di accesso condiviso di delega utente offre una protezione maggiore rispetto a una firma di accesso condiviso firmata con la chiave dell'account di archiviazione. Quando possibile, Microsoft consiglia di usare una firma di accesso condiviso di delega utente. Per altre informazioni, vedere Concedere accesso limitato ai dati con firme di accesso condiviso.

Questo articolo illustra come usare la chiave dell'account di archiviazione per creare una firma di accesso condiviso del servizio per un contenitore o un BLOB con la libreria client di Archiviazione BLOB di Azure per .NET.

Informazioni sul servizio SAS

Un servizio SAS viene firmato con la chiave di accesso dell'account. È possibile usare la classe StorageSharedKeyCredential per creare le credenziali usate per firmare il servizio SAS.

È anche possibile usare criteri di accesso archiviati per definire le autorizzazioni e la durata della firma di accesso condiviso. Se viene specificato il nome di un criterio di accesso archiviato esistente, tale criterio è associato alla firma di accesso condiviso. Per maggiori informazioni sui criteri di accesso archiviati, vedere Definire un criterio di accesso archiviato. Se non vengono forniti criteri di accesso archiviati, gli esempi di codice in questo articolo illustrano come definire le autorizzazioni e la durata per la firma di accesso condiviso.

Creare un SAS di servizio

È possibile creare un servizio SAS per un contenitore o un BLOB, in base alle esigenze dell'app.

L'esempio di codice seguente mostra come creare un servizio SAS per una risorsa contenitore. In primo luogo, il codice verifica che l'oggetto BlobContainerClient sia autorizzato con credenziali di chiave condivisa, controllando la proprietà CanGenerateSasUri . Genera quindi la firma di accesso condiviso del servizio tramite la classe BlobSasBuilder e chiama GenerateSasUri per creare un URI di firma di accesso condiviso del servizio basato sugli oggetti client e builder.

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

Usare una firma di accesso condiviso del servizio per autorizzare un oggetto client

È possibile usare una firma di accesso condiviso del servizio per autorizzare un oggetto client a eseguire operazioni su un contenitore o un BLOB, in base alle autorizzazioni concesse dalla firma di accesso condiviso.

Gli esempi di codice seguenti illustrano come usare la firma di accesso condiviso del servizio per autorizzare un oggetto BlobContainerClient. Questo oggetto client può essere usato per eseguire operazioni sulla risorsa del contenitore in base alle autorizzazioni concesse dalla firma di accesso condiviso.

Creare prima di tutto un oggetto BlobServiceClient firmato con la chiave di accesso dell'account:

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

Generare quindi la firma di accesso condiviso come illustrato nell'esempio precedente e usare la firma di accesso condiviso per autorizzare un oggetto BlobContainerClient:

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

Definire criteri di accesso archiviati

I criteri di accesso archiviati forniscono un livello di controllo aggiuntivo sulle firme di accesso condiviso (SAS) a livello di servizio sul lato server. La definizione di un criterio di accesso archiviato permette di raggruppare le firme di accesso condiviso e fornire limitazioni aggiuntive per le firme vincolate dal criterio.

È possibile usare un criterio di accesso archiviato per modificare l'ora di inizio, l'ora di scadenza o le autorizzazioni per una firma. È anche possibile usare un criterio di accesso archiviato per revocare una firma dopo che è stata rilasciata. Questa sezione è incentrata sui contenitori BLOB, ma i criteri di accesso archiviati sono supportati anche per condivisioni file, code e tabelle.

Per gestire i criteri di accesso archiviati in una risorsa contenitore, chiamare uno dei metodi seguenti da un oggetto BlobContainerClient:

Creare o modificare criteri di accesso archiviati

È possibile impostare un massimo di cinque criteri di accesso alla volta, per singola risorsa. A ciascun SignedIdentifier campo, con il relativo campo Id univoco, corrisponde un criterio di accesso. Se si tenta di impostare più di cinque criteri di accesso contemporaneamente, il servizio restituisce il codice di stato 400 (Bad Request).

L'esempio di codice seguente illustra come creare due criteri di accesso archiviati in una risorsa contenitore:

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

È anche possibile modificare un criterio esistente. L'esempio di codice seguente illustra come modificare un singolo criterio di accesso archiviato per aggiornare la data di scadenza dei criteri:

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

Come eliminare o revocare criteri di accesso archiviati

Per revocare un criterio di accesso archiviato, Microsoft consiglia di eliminare l'identificatore firmato e crearne uno nuovo. La modifica dell'identificatore firmato interrompe le associazioni tra eventuali firme esistenti e il criterio di accesso archiviato. L'eliminazione o modifica dei criteri di accesso archiviati interessa con effetto immediato tutte le firme di accesso condiviso ad essi associate.

Nell'esempio di codice seguente, viene illustrato come revocare un criterio, modificando la Id proprietà per l'identificatore firmato. Questo approccio elimina efficacemente l'identificatore firmato e ne crea uno nuovo:

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

È anche possibile rimuovere tutti i criteri di accesso da una risorsa contenitore chiamando SetAccessPolicyAsync con un parametro vuoto permissions. L'esempio seguente mostra come eliminare tutti i criteri di accesso archiviati da un contenitore specificato:

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

Risorse

Per maggiori informazioni sulla creazione di una firma di accesso condiviso del servizio usando la libreria client di Archiviazione BLOB di Azure per .NET, vedere le risorse seguenti.

Esempi di codice

Risorse della libreria client

Vedi anche