使用 Java 为 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)。

本文介绍如何使用适用于 Java 的 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 角色。

设置项目

若要使用本文中的代码示例，请添加以下导入指令：

import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;
import com.azure.storage.blob.sas.*;

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

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

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

BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
        .endpoint("https://<storage-account-name>.blob.core.chinacloudapi.cn/")
        .credential(new DefaultAzureCredentialBuilder().build())
        .buildClient();

若要详细了解如何使用 Java SDK 从应用程序授权对 Blob 存储的访问，请参阅使用 Java 和 Azure 标识进行 Azure 身份验证。

获取用户委托密钥

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

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

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

getUserDelegationKey

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

public UserDelegationKey requestUserDelegationKey(BlobServiceClient blobServiceClient) {
    // Request a user delegation key that's valid for 1 day, as an example
    UserDelegationKey userDelegationKey = blobServiceClient.getUserDelegationKey(
        OffsetDateTime.now().minusMinutes(5),
        OffsetDateTime.now().plusDays(1));

    return userDelegationKey;
}

为 blob 创建用户委托 SAS

获取用户委托密钥后，可以创建用户委托 SAS。可以使用以下方法通过 BlobClient 实例创建用户委托 SAS，以委派对 blob 资源的有限访问权限：

generateUserDelegationSas

用于对 SAS 进行签名的用户委派密钥连同 BlobServiceSasSignatureValues 的指定值一起传递给此方法。权限指定为 BlobSasPermission 实例。

以下代码示例演示如何为 blob 创建用户委托 SAS：

public String createUserDelegationSASBlob(BlobClient blobClient, UserDelegationKey userDelegationKey) {
    // Create a SAS token that's valid for 1 day, as an example
    OffsetDateTime expiryTime = OffsetDateTime.now().plusDays(1);

    // Assign read permissions to the SAS token
    BlobSasPermission sasPermission = new BlobSasPermission()
            .setReadPermission(true);

    BlobServiceSasSignatureValues sasSignatureValues = new BlobServiceSasSignatureValues(expiryTime, sasPermission)
            .setStartTime(OffsetDateTime.now().minusMinutes(5));

    String sasToken = blobClient.generateUserDelegationSas(sasSignatureValues, userDelegationKey);
    return sasToken;
}

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

以下代码示例显示了如何使用在较早的示例中创建的用户委托 SAS 来授权 BlobClient 对象。此客户端对象可用于根据 SAS 授予的权限对 blob 资源执行操作。

// Create a SAS token for a blob
BlobClient blobClient = blobServiceClient
        .getBlobContainerClient("sample-container")
        .getBlobClient("sample-blob.txt");
String sasToken = createUserDelegationSASBlob(blobClient, userDelegationKey);

// Create a new BlobClient using the SAS token
BlobClient sasBlobClient = new BlobClientBuilder()
        .endpoint(blobClient.getBlobUrl())
        .sasToken(sasToken)
        .buildClient();

资源

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

REST API 操作

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

使用 Java 为 blob 创建用户委托 SAS

关于用户委托 SAS

分配可访问数据的 Azure 角色

设置项目

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

获取用户委托密钥

为 blob 创建用户委托 SAS

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

资源

REST API 操作

代码示例

客户端库资源

另请参阅

其他资源