使用 .NET 建立 Blob 的使用者委派 SAS

  • 發行項

共用存取簽章 (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) 授與資料的有限存取權。

本文說明如何使用 Microsoft Entra 認證，透過適用於 .NET 的 Azure 儲存體用戶端程式庫為 Blob 建立使用者委派 SAS。

關於使用者委派 SAS

您可以使用 Microsoft Entra 認證或帳戶金鑰保護存取容器或 Blob 的 SAS 權杖。 使用 Microsoft Entra 認證保護的 SAS 稱為使用者委派 SAS，因為用來簽署 SAS 的 OAuth 2.0 權杖是代表該使用者而要求的。

Microsoft 建議您的安全性最佳做法是盡可能使用 Microsoft Entra 認證，而不是使用帳戶金鑰，因為後者可能更容易遭到盜用。 當您的應用程式設計需要共用存取簽章時，請使用 Microsoft Entra 認證來建立使用者委派 SAS 以獲得較佳的安全性。 如需使用者委派 SAS 的詳細資訊，請參閱建立使用者委派 SAS。

警告

擁有有效 SAS 的任何用戶端在該 SAS 允許的範圍內，可存取儲存體帳戶中的資料。 保護 SAS 防止遭到惡意使用或誤用至關重要。 在散發 SAS 時請謹慎使用，並備妥方案以撤銷遭盜用的 SAS。

如需共用存取簽章的詳細資訊，請參閱使用共用存取簽章 (SAS) 授與 Azure 儲存體資源的有限存取權。

指派存取資料的 Azure 角色

當 Microsoft Entra 安全性主體嘗試存取 Blob 資料時，該安全性主體必須具有該資源的權限。 無論安全性主體是 Azure 中的受控識別，或是在開發環境中執行程式碼的 Microsoft Entra 使用者帳戶，都必須為安全性主體指派授與 Blob 資料存取權的 Azure 角色。 如需透過 Azure RBAC 指派權限的相關資訊，請參閱指派 Azure 角色以存取 Blob 資料。

設定您的專案

若要使用本文中的程式碼範例，請遵循下列步驟來設定您的專案。

安裝套件

安裝下列套件：

dotnet add package Azure.Identity
dotnet add 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 類別的執行個體。 如需使用 Default AzureCredential 類別來授權受控識別以存取 Blob 儲存體的詳細資訊，請參閱適用於 .NET 的 Azure 身分識別用戶端程式庫 (英文版)。

下列程式碼片段說明如何取得已驗證的權杖認證，並用其建立 Blob 儲存體的服務用戶端：

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

// 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.BlobContainerName,
        BlobName = 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 操作

適用於 .NET 的 Azure SDK 包含建置在 Azure REST API 之上的程式庫，可讓您透過熟悉的 .NET 範例與 REST API 作業進行互動。 取得使用者委派金鑰的用戶端程式庫方法會使用下列 REST API 作業：

用戶端程式庫資源

另請參閱