Azure Blob Depolama ve JavaScript ile kullanıcı temsilcisi SAS belirteci oluşturma

Bu makalede JavaScript için Azure Blob Depolama istemci kitaplığı v12'de kullanıcı temsilcisi SAS belirtecinin nasıl oluşturulacağı gösterilmektedir. Sürüm 2018-11-09 ile sunulan kullanıcı temsilcisi SAS'sinin güvenliği Microsoft Entra kimlik bilgileriyle sağlanır ve yalnızca Blob hizmeti için aşağıdakiler için desteklenir:

• Mevcut bir kapsayıcıya erişim izni verme.
• Blob oluşturma, kullanma ve silme erişimi verme.

Kullanıcı temsilcisi SAS'ı oluşturmak için istemcinin blobServiceClient.getUserDelegationKey işlemini çağırma izinleri olmalıdır. Bu işlem tarafından döndürülen anahtar, kullanıcı temsilcisi SAS'sini imzalamak için kullanılır. Bu işlemi çağıran güvenlik sorumlusuna Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey/action içeren bir RBAC rolü atanmalıdır.

SAS'ye sahip bir istemciye verilen izinler, kullanıcı temsilci anahtarını isteyen güvenlik sorumlusuna verilen izinlerin ve imzalı izinler (sp) alanındaki SAS belirtecindeki kaynağa verilen izinlerin kesişimidir. Güvenlik sorumlusuna RBAC aracılığıyla verilen bir izin SAS belirtecinde de verilmediyse, bu izin kaynağa erişmek için SAS'yi kullanmaya çalışan istemciye verilmez.

Örnek kod parçacıkları GitHub'da çalıştırılabilir Node.js dosyaları olarak kullanılabilir.

Paket (npm) | Örnekler | API başvurusu | Kitaplık kaynak kodu | Geri BildirimDeğer Ver

Kullanıcı temsilcisi SAS belirteçleri için en iyi yöntemler

SAS belirtecine sahip herkes kapsayıcıya ve bloblara erişmek için bunu kullanabildiğinden, belirtecin gerekli görevleri tamamlamasına izin veren en kısıtlayıcı izinlerle SAS belirtecini tanımlamanız gerekir.

SAS belirteçleri için en iyi yöntemler

Azure Cloud'da DefaultAzureCredential'i kullanma

Azure'da gizli diziler olmadan kimlik doğrulaması yapmak için yönetilen kimliği ayarlayın. Bu yaklaşım, kodunuzun DefaultAzureCredential kullanmasını sağlar.

Azure bulutu için yönetilen kimliği ayarlamak için:

• Yönetilen kimlik oluşturma
• Kimlik için uygun Depolama rollerini ayarlama
• Azure ortamınızı yönetilen kimliğinizle çalışacak şekilde yapılandırma

Bu iki görev tamamlandığında, bağlantı dizesi veya hesap anahtarı yerine DefaultAzureCredential kullanın. Bu yaklaşım, tüm ortamlarınızın kaynak kodunda gizli dizileri kullanma sorunu olmadan tam olarak aynı kaynak kodunu kullanmasına olanak tanır.

Yerel geliştirmede DefaultAzureCredential'i kullanma

Yerel geliştirme ortamınızda Azure kimliğinizin (Azure portalında oturum açmak için kullandığınız kişisel veya geliştirme hesabınız) yerel ve bulut çalışma zamanlarında aynı kodu kullanmak için Azure'da kimlik doğrulaması yapması gerekir.

Kapsayıcı: Uygulamanıza gerekli bağımlılıkları ekleme

Kapsayıcı SAS belirteci oluşturmak için gerekli bağımlılıkları ekleyin.

const {
    DefaultAzureCredential
} = require('@azure/identity');
const {
    ContainerClient,
    BlobServiceClient,
    ContainerSASPermissions,
    generateBlobSASQueryParameters,
    SASProtocol
} = require('@azure/storage-blob');

// used for local environment variables
require('dotenv').config();

Kapsayıcı: ortam değişkenlerini alma

Blob Depolama hesabı adı ve kapsayıcı adı, kapsayıcı SAS belirteci oluşturmak için gereken en düşük değerlerdir:

// Get environment variables for DefaultAzureCredential
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
const containerName = process.env.AZURE_STORAGE_BLOB_CONTAINER_NAME;

DefaultAzureCredential ile SAS oluşturma

DefaultAzureCredential ile SAS belirteci oluşturmak için aşağıdaki kavramsal adımlar gereklidir:

• DefaultAzureCredential'i ayarlama
  • Yerel geliştirme - kişisel kimlik kullanma ve depolama için rolleri ayarlama
  • Azure bulutu - yönetilen kimlik oluşturma
• UserDelegationKey ile kullanıcı temsilci anahtarını almak için DefaultAzureCredential kullanın
• GenerateBlobSASQueryParameters ile uygun alanlarla SAS belirtecini oluşturmak için kullanıcı temsilcisi anahtarını kullanın

Kapsayıcı: DefaultAzureCredential ile SAS belirteci oluşturma

Kimlik yapılandırıldığında, mevcut bir hesap ve kapsayıcı için Kullanıcı temsilcisi SAS belirteci oluşturmak için aşağıdaki kodu kullanın:

// Server creates User Delegation SAS Token for container
async function createContainerSas() {

    // Get environment variables
    const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
    const containerName = process.env.AZURE_STORAGE_BLOB_CONTAINER_NAME;

    // Best practice: create time limits
    const TEN_MINUTES = 10 * 60 * 1000;
    const NOW = new Date();

    // Best practice: set start time a little before current time to 
    // make sure any clock issues are avoided
    const TEN_MINUTES_BEFORE_NOW = new Date(NOW.valueOf() - TEN_MINUTES);
    const TEN_MINUTES_AFTER_NOW = new Date(NOW.valueOf() + TEN_MINUTES);

    // Best practice: use managed identity - DefaultAzureCredential
    const blobServiceClient = new BlobServiceClient(
        `https://${accountName}.blob.core.windows.net`,
        new DefaultAzureCredential()
      );

    // Best practice: delegation key is time-limited  
    // When using a user delegation key, container must already exist 
    const userDelegationKey = await blobServiceClient.getUserDelegationKey(
        TEN_MINUTES_BEFORE_NOW, 
        TEN_MINUTES_AFTER_NOW
    );

    // Need only list permission to list blobs 
    const containerPermissionsForAnonymousUser = "l";

    // Best practice: SAS options are time-limited
    const sasOptions = {
        containerName,                                           
        permissions: ContainerSASPermissions.parse(containerPermissionsForAnonymousUser), 
        protocol: SASProtocol.HttpsAndHttp,
        startsOn: TEN_MINUTES_BEFORE_NOW,
        expiresOn: TEN_MINUTES_AFTER_NOW
    };
 
    const sasToken = generateBlobSASQueryParameters(
        sasOptions,
        userDelegationKey,
        accountName 
    ).toString();

    return sasToken;
}

Yukarıdaki sunucu kodu, kapsayıcı SAS belirtecini oluşturmak için bir değer akışı oluşturur:

• DefaultAzureCredential ile BlobServiceClient oluşturma
• UserDelegationKey oluşturmak için blobServiceClient.getUserDelegationKey işlemini kullanın
• generateBlobSASQueryParameters ile SAS belirteç dizesini oluşturmak için anahtarını kullanın

Kapsayıcı SAS belirtecini oluşturduktan sonra belirteci kullanacak istemciye sağlayabilirsiniz. İstemci daha sonra kapsayıcıdaki blobları listelemek için bunu kullanabilir. İstemci kodu örneği , SAS'nin tüketici olarak nasıl test yapılacağını gösterir.

Kapsayıcı: SAS belirtecini kullanma

Kapsayıcı SAS belirteci oluşturulduktan sonra belirteci kullanın. SAS belirtecini kullanma örneği olarak şunları yapın:

• Kapsayıcı adı ve sorgu dizesi dahil olmak üzere tam BIR URL oluşturun. Sorgu dizesi SAS belirtecidir.
• Kapsayıcı URL'si ile bir ContainerClient oluşturun.
• İstemciyi kullanın: Bu örnekte, kapsayıcıdaki blobları listBlobsFlat ile listeleyin.

// Client or another process uses SAS token to use container
async function listBlobs(sasToken){

    // Get environment variables
    const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
    const containerName = process.env.AZURE_STORAGE_BLOB_CONTAINER_NAME;
    
    // Create Url
    // SAS token is the query string with typical `?` delimiter
    const sasUrl = `https://${accountName}.blob.core.windows.net/${containerName}?${sasToken}`;
    console.log(`\nContainerUrl = ${sasUrl}\n`);

    // Create container client from SAS token url
    const containerClient = new ContainerClient(sasUrl);

    let i = 1;

    // List blobs in container
    for await (const blob of containerClient.listBlobsFlat()) {
        console.log(`Blob ${i++}: ${blob.name}`);
    }    
}

Blob: Uygulamanıza gerekli bağımlılıkları ekleme

n blob SAS belirteci oluşturmak için gerekli bağımlılıkları ekleyin.

const {
    DefaultAzureCredential
} = require('@azure/identity');
const {
    BlockBlobClient,
    BlobServiceClient,
    BlobSASPermissions,
    generateBlobSASQueryParameters,
    SASProtocol
} = require('@azure/storage-blob');

// used for local environment variables
require('dotenv').config();

Blob: ortam değişkenlerini alma

Blob Depolama hesabı adı ve kapsayıcı adı, blob SAS belirteci oluşturmak için gereken en düşük değerlerdir:

const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
const containerName = process.env.AZURE_STORAGE_BLOB_CONTAINER_NAME;

Bir blob SAS belirteci oluşturmanız gerektiğinde, SAS belirtecini oluşturmak için blob adına sahip olmanız gerekir. Bu, rastgele blob adı, kullanıcı tarafından gönderilen blob adı veya uygulamanızdan oluşturulan ad gibi önceden belirlenecektir.

// Create random blob name for text file
const blobName = `${(0|Math.random()*9e6).toString(36)}.txt`;

Blob: DefaultAzureCredential ile SAS belirteci oluşturma

Kimlik yapılandırıldığında, mevcut bir hesap ve kapsayıcı için Kullanıcı temsilcisi SAS belirteci oluşturmak için aşağıdaki kodu kullanın:

// Server creates User Delegation SAS Token for blob
async function createBlobSas(blobName) {

    // Get environment variables
    const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
    const containerName = process.env.AZURE_STORAGE_BLOB_CONTAINER_NAME;

    // Best practice: create time limits
    const TEN_MINUTES = 10 * 60 * 1000;
    const NOW = new Date();

    // Best practice: set start time a little before current time to 
    // make sure any clock issues are avoided
    const TEN_MINUTES_BEFORE_NOW = new Date(NOW.valueOf() - TEN_MINUTES);
    const TEN_MINUTES_AFTER_NOW = new Date(NOW.valueOf() + TEN_MINUTES);

    // Best practice: use managed identity - DefaultAzureCredential
    const blobServiceClient = new BlobServiceClient(
        `https://${accountName}.blob.core.windows.net`,
        new DefaultAzureCredential()
      );

    // Best practice: delegation key is time-limited  
    // When using a user delegation key, container must already exist 
    const userDelegationKey = await blobServiceClient.getUserDelegationKey(
        TEN_MINUTES_BEFORE_NOW, 
        TEN_MINUTES_AFTER_NOW
    );

    // Need only create/write permission to upload file
    const blobPermissionsForAnonymousUser = "cw"

    // Best practice: SAS options are time-limited
    const sasOptions = {
        blobName,
        containerName,                                           
        permissions: BlobSASPermissions.parse(blobPermissionsForAnonymousUser), 
        protocol: SASProtocol.HttpsAndHttp,
        startsOn: TEN_MINUTES_BEFORE_NOW,
        expiresOn: TEN_MINUTES_AFTER_NOW
    };
 
    const sasToken = generateBlobSASQueryParameters(
        sasOptions,
        userDelegationKey,
        accountName 
    ).toString();

    return sasToken;
}

Yukarıdaki kod, kapsayıcı SAS belirtecini oluşturmak için bir değer akışı oluşturur:

• DefaultAzureCredential ile BlobServiceClient oluşturma
• UserDelegationKey oluşturmak için blobServiceClient.getUserDelegationKey işlemini kullanın
• SAS belirteci dizesini oluşturmak için anahtarını kullanın. Blob adı seçeneklerde belirtilmemişse SAS belirteci bir kapsayıcı belirtecidir.

Blob SAS belirtecini oluşturduktan sonra belirteci kullanacak istemciye sağlayabilirsiniz. İstemci daha sonra blobu karşıya yüklemek için kullanabilir. İstemci kodu örneği , SAS'nin tüketici olarak nasıl test yapılacağını gösterir.

Blob: SAS belirtecini kullanma

Blob SAS belirteci oluşturulduktan sonra belirteci kullanın. SAS belirtecini kullanma örneği olarak şunları yapın:

• Kapsayıcı adı, blob adı ve sorgu dizesi dahil olmak üzere tam bir URL oluşturun. Sorgu dizesi SAS belirtecidir.
• Kapsayıcı URL'si ile bir BlockBlobClient oluşturun.
• İstemciyi kullanın: Bu örnekte karşıya yükleme ile blobu karşıya yükleyin.

// Client or another process uses SAS token to upload content to blob
async function uploadStringToBlob(blobName, sasToken, textAsString){

    // Get environment variables
    const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
    const containerName = process.env.AZURE_STORAGE_BLOB_CONTAINER_NAME;

    // Create Url SAS token as query string with typical `?` delimiter
    const sasUrl = `https://${accountName}.blob.core.windows.net/${containerName}/${blobName}?${sasToken}`;
    console.log(`\nBlobUrl = ${sasUrl}\n`);

    // Create blob client from SAS token url
    const blockBlobClient = new BlockBlobClient(sasUrl);

    // Upload string
    await blockBlobClient.upload(textAsString, textAsString.length, undefined);    
}

Ayrıca bkz.

• SAS belirteci türleri
• API başvurusu
• Kitaplık kaynak kodu
• Geri BildirimDe bulunmak