使用 Python 建立容器的使用者委派 SAS

發行項
03/21/2024

共用存取簽章 (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 認證，透過適用於 Python 的 Azure 儲存體用戶端程式庫為容器建立使用者委派 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 資料。

設定您的專案

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

安裝套件

使用 pip install 安裝下列套件：

pip install azure-storage-blob azure-identity

設定應用程式程式碼

新增下列 import 指示詞：

from azure.identity import DefaultAzureCredential
from azure.storage.blob import (
    BlobServiceClient,
    ContainerClient,
    BlobClient,
    BlobSasPermissions,
    ContainerSasPermissions,
    UserDelegationKey,
    generate_container_sas,
    generate_blob_sas
)

取得已驗證的權杖認證

若要取得程式碼可用來授權 Blob 儲存體要求的權杖認證，請建立 DefaultAzureCredential 類別的執行個體。如需使用 DefaultAzureCredential 類別來授權受控識別以存取 Blob 儲存體的詳細資訊，請參閱適用於 Python 的 Azure 身分識別用戶端程式庫。

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

# Construct the blob endpoint from the account name
account_url = "https://<storage-account-name>.blob.core.windows.net"

#Create a BlobServiceClient object using DefaultAzureCredential
blob_service_client = BlobServiceClient(account_url, credential=DefaultAzureCredential())

若要深入了解如何使用 Python SDK 從您的應用程式授權 Blob 儲存體的存取權，請參閱向 Azure 服務驗證 Python 應用程式。

取得使用者委派金鑰

每個 SAS 都會以金鑰簽署。若要建立使用者委派 SAS，您必須先要求使用者委派金鑰，然後使用該金鑰來簽署 SAS。使用者委派金鑰類似用來簽署服務 SAS 或帳戶 SAS 的帳戶金鑰，不同之處在於其依賴您的 Microsoft Entra 認證。當用戶端使用 OAuth 2.0 權杖要求使用者委派金鑰時，Blob 儲存體會代表使用者傳回使用者委派金鑰。

擁有使用者委派金鑰之後，您就可以使用該金鑰，在金鑰存留期內建立任意數量的使用者委派共用存取簽章。使用者委派金鑰與用來取得該金鑰的 OAuth 2.0 權杖無關，因此只要金鑰仍有效，就不需要更新權杖。您可以指定金鑰維持有效的時間長度，最多七天。

您可以使用下列其中一種方法來要求使用者委派金鑰：

get_user_delegation_key

下列程式碼範例說明如何要求使用者委派金鑰：

def request_user_delegation_key(self, blob_service_client: BlobServiceClient) -> UserDelegationKey:
    # Get a user delegation key that's valid for 1 day
    delegation_key_start_time = datetime.datetime.now(datetime.timezone.utc)
    delegation_key_expiry_time = delegation_key_start_time + datetime.timedelta(days=1)

    user_delegation_key = blob_service_client.get_user_delegation_key(
        key_start_time=delegation_key_start_time,
        key_expiry_time=delegation_key_expiry_time
    )

    return user_delegation_key

建立容器的使用者委派 SAS

取得使用者委派金鑰之後，即可建立使用者委派 SAS。您可以使用下列方法來建立使用者委派 SAS，以委派對容器資源的有限存取權：

generate_container_sas

用來簽署 SAS 的使用者委派金鑰會以 user_delegation_key 引數的形式傳遞至方法。允許的權限會作為 permission 引數傳遞至方法，並定義於 ContainerSasPermissions 類別中。

下列程式碼範例說明如何建立容器的使用者委派 SAS：

def create_user_delegation_sas_container(self, container_client: ContainerClient, user_delegation_key: UserDelegationKey):
    # Create a SAS token that's valid for one day, as an example
    start_time = datetime.datetime.now(datetime.timezone.utc)
    expiry_time = start_time + datetime.timedelta(days=1)

    sas_token = generate_container_sas(
        account_name=container_client.account_name,
        container_name=container_client.container_name,
        user_delegation_key=user_delegation_key,
        permission=ContainerSasPermissions(read=True),
        expiry=expiry_time,
        start=start_time
    )

    return sas_token

利用使用者委派 SAS 來授權用戶端物件

下列程式碼範例示範如何使用先前範例中所建立的使用者委派 SAS 來授權 ContainerClient 物件。此用戶端物件可用來根據 SAS 授與的權限，在容器資源上執行作業。

# The SAS token string can be appended to the resource URL with a ? delimiter
# or passed as the credential argument to the client constructor
sas_url = f"{container_client.url}?{sas_token}"

# Create a ContainerClient object with SAS authorization
container_client_sas = ContainerClient.from_container_url(container_url=sas_url)

資源

若要深入了解如何使用適用於 Python 的 Azure Blob 儲存體用戶端程式庫來建立使用者委派 SAS，請參閱下列資源。

REST API 操作

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

共用方式為