使用 .NET 为 blob 创建用户委托 SAS

项目
12/21/2023

使用共享访问签名 (SAS)，可以授予对存储帐户中容器和 blob 的有限访问权限。创建 SAS 时，需要指定其约束条件，包括允许客户端访问哪些 Azure 存储资源、它们对这些资源具有哪些权限，以及 SAS 的有效期。

每个 SAS 均使用密钥进行签名。可通过以下两种方式之一对 SAS 进行签名：

使用通过 Microsoft Entra 凭据创建的密钥。使用 Microsoft Entra 凭据签名的 SAS 是用户委托 SAS。必须为创建用户委托 SAS 的客户端分配一个 Azure RBAC 角色，该角色包括 Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey 操作。若要了解详细信息，请参阅创建用户委托 SAS。
使用存储帐户密钥。服务 SAS 和帐户 SAS 均使用存储帐户密钥进行签名。创建服务 SAS 的客户端必须具有对帐户密钥的直接访问权限，或分配有 Microsoft.Storage/storageAccounts/listkeys/action 权限。若要了解详细信息，请参阅创建服务 SAS 或创建帐户 SAS。

注意

用户委托 SAS 为使用存储帐户密钥签名的 SAS 提供更高的安全性。 Microsoft 建议尽可能使用用户委托 SAS。有关详细信息，请参阅向具有共享访问签名的数据授予有限的访问权限 (SAS)。

本文介绍了如何使用适用于.NET 的 Azure 存储客户端库通过 Microsoft Entra 凭据为 blob 创建用户委托 SAS。

关于用户委托 SAS

可使用 Microsoft Entra 凭据或帐户密钥来保护用于访问容器或 Blob 的 SAS 令牌。使用 Microsoft Entra 凭据保护的 SAS 称为用户委派 SAS，因为用于签署 SAS 的 OAuth 2.0 令牌是代表用户请求的。

Azure 建议你尽可能使用 Microsoft Entra 凭据，而不要使用更容易受到安全威胁的帐户密钥，这是安全性方面的最佳做法。当应用程序设计需要共享访问签名时，请使用 Microsoft Entra 凭据创建可提供超高安全性的用户委派 SAS。有关用户委托 SAS 的详细信息，请参阅创建用户委托 SAS。

注意

拥有有效 SAS 的任何客户端都可以访问该 SAS 允许的存储帐户中的数据。防止 SAS 被恶意使用或意料之外的使用很重要。请谨慎分发 SAS，并制定撤销受到安全威胁的 SAS 的计划。

有关共享访问签名的详细信息，请参阅使用共享访问签名 (SAS) 授予对 Azure 存储资源的有限访问权限。

分配可访问数据的 Azure 角色

当 Microsoft Entra 安全主体尝试访问 Blob 数据时，该安全主体必须具有对资源的访问权限。不管安全主体是 Azure 中的托管标识还是在开发环境中运行代码的 Microsoft Entra 用户帐户，都必须为安全主体分配一个 Azure 角色，由该角色授权访问 Blob 数据。有关通过 Azure RBAC 分配权限的信息，请参阅分配用于访问 Blob 数据的 Azure 角色。

设置项目

要使用本文中的代码示例，请按照以下步骤设置项目。

安装包

安装以下包：

.NET CLI
PowerShell

dotnet add package Azure.Identity
dotnet add package Azure.Storage.Blobs

Install-Package Azure.Identity
Install-Package Azure.Storage.Blobs

设置应用代码

然后，添加以下 using 指令：

using Azure;
using Azure.Identity;
using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using Azure.Storage.Blobs.Specialized;
using Azure.Storage.Sas;

获取经过身份验证的令牌凭据

若要获取令牌凭据，以便代码用它来授权对 Blob 存储的请求，请创建 DefaultAzureCredential 类的实例。若要详细了解如何使用 DefaultAzureCredential 类来授权托管标识访问 Blob 存储，请参阅适用于 .NET 的 Azure 标识客户端库。

以下代码片段演示了如何获取经身份验证的令牌凭据并使用它来为 Blob 存储创建服务客户端：

// Construct the blob endpoint from the account name.
string endpoint = $"https://{accountName}.blob.core.chinacloudapi.cn";

// Create a blob service client object using DefaultAzureCredential
BlobServiceClient blobServiceClient = new BlobServiceClient(
    new Uri(endpoint),
    new DefaultAzureCredential());

若要详细了解如何使用 .NET SDK 从应用程序授权访问 Blob 存储，请参阅如何使用 Azure 服务对 .NET 应用程序进行身份验证。

获取用户委托密钥

每个 SAS 均使用密钥进行签名。若要创建用户委托 SAS，必须首先请求用户委托密钥，然后使用该密钥对 SAS 进行签名。用户委派密钥与用于对服务 SAS 或帐户 SAS 签名的帐户密钥类似，只不过它依赖于 Microsoft Entra 凭据。当客户端使用 OAuth 2.0 令牌请求用户委托密钥时，Blob 存储将代表该用户返回用户委托密钥。

拥有用户委托密钥后，你就可以在该密钥的生存期内使用该密钥创建任意数量的用户委托共享访问签名。用户委派密钥与用于获取该密钥的 OAuth 2.0 令牌相互独立，因此只要密钥仍有效，就不必续订令牌。可以指定密钥保持有效的时间长度，最长为七天。

使用以下方法之一请求用户委托密钥：

以下代码示例演示如何请求用户委托密钥：

public static async Task<UserDelegationKey> RequestUserDelegationKey(
    BlobServiceClient blobServiceClient)
{
    // Get a user delegation key for the Blob service that's valid for 1 day
    UserDelegationKey userDelegationKey =
        await blobServiceClient.GetUserDelegationKeyAsync(
            DateTimeOffset.UtcNow,
            DateTimeOffset.UtcNow.AddDays(1));

    return userDelegationKey;
}

为 blob 创建用户委托 SAS

获取用户委托密钥后，可以创建用户委托 SAS，以委派对 blob 资源的有限访问权限。以下代码示例演示如何为 blob 创建用户委托 SAS：

public static async Task<Uri> CreateUserDelegationSASBlob(
    BlobClient blobClient,
    UserDelegationKey userDelegationKey)
{
    // Create a SAS token for the blob resource that's also valid for 1 day
    BlobSasBuilder sasBuilder = new BlobSasBuilder()
    {
        BlobContainerName = blobClient.Name,
        Resource = "b",
        StartsOn = DateTimeOffset.UtcNow,
        ExpiresOn = DateTimeOffset.UtcNow.AddDays(1)
    };

    // Specify the necessary permissions
    sasBuilder.SetPermissions(BlobSasPermissions.Read | BlobSasPermissions.Write);

    // Add the SAS token to the blob URI
    BlobUriBuilder uriBuilder = new BlobUriBuilder(blobClient.Uri)
    {
        // Specify the user delegation key
        Sas = sasBuilder.ToSasQueryParameters(
            userDelegationKey,
            blobClient
            .GetParentBlobContainerClient()
            .GetParentBlobServiceClient().AccountName)
    };

    return uriBuilder.ToUri();
}

使用用户委托 SAS 为客户端对象授权

以下代码示例演示如何使用用户委派 SAS 授权 BlobClient 对象。此客户端对象可用于根据 SAS 授予的权限对 blob 资源执行操作。

// Create a Uri object with a user delegation SAS appended
BlobClient blobClient = blobServiceClient
    .GetBlobContainerClient("sample-container")
    .GetBlobClient("sample-blob.txt");
Uri blobSASURI = await CreateUserDelegationSASBlob(blobClient, userDelegationKey);

// Create a blob client object with SAS authorization
BlobClient blobClientSAS = new BlobClient(blobSASURI);

资源

要详细了解如何使用适用于 .NET 的 Azure Blob 存储客户端库来创建用户委派 SAS，请参阅以下资源。

REST API 操作

Azure SDK for .NET 包含基于 Azure REST API 而生成的库，允许你通过熟悉的 .NET 范例与 REST API 操作进行交互。用于获取用户委派密钥的客户端库方法使用以下 REST API 操作：

获取用户委派密钥 (REST API)