Membuat token SAS delegasi pengguna dengan Azure Blob Storage dan JavaScript

Artikel ini menunjukkan cara membuat token SAS delegasi pengguna di pustaka klien Azure Blob Storage v12 untuk JavaScript. DELEGASI pengguna SAS, yang diperkenalkan dengan versi 2018-11-09, diamankan dengan kredensial Microsoft Entra dan didukung untuk layanan Blob hanya untuk:

Berikan akses ke kontainer yang ada.
Berikan akses untuk membuat, menggunakan, dan menghapus blob.

Untuk membuat SAS delegasi pengguna, klien harus memiliki izin untuk memanggil operasi blobServiceClient.getUserDelegationKey. Kunci yang dikembalikan oleh operasi ini digunakan untuk menandatangani SAS delegasi pengguna. Prinsipal keamanan yang memanggil operasi ini harus diberi peran RBAC yang mencakup Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey/action.

Izin yang diberikan kepada klien yang memiliki SAS adalah persimpangan izin yang diberikan kepada prinsipal keamanan yang meminta kunci delegasi pengguna dan izin yang diberikan ke sumber daya pada token SAS di bidang izin (sp) yang ditandatangani. Jika izin yang diberikan kepada prinsipal keamanan melalui RBAC tidak juga diberikan pada token SAS, izin tersebut tidak diberikan kepada klien yang mencoba menggunakan SAS untuk mengakses sumber daya.

Cuplikan kode sampel tersedia di GitHub sebagai file Node.js yang dapat dijalankan.

Paket (npm) | Contoh | referensi API | Kode sumber pustaka | Berikan Umpan Balik

Praktik terbaik untuk token SAS delegasi pengguna

Karena siapa pun yang memiliki token SAS dapat menggunakannya untuk mengakses kontainer dan blob, Anda harus menentukan token SAS dengan izin paling ketat yang masih memungkinkan token untuk menyelesaikan tugas yang diperlukan.

Praktik terbaik untuk token SAS

Menggunakan DefaultAzureCredential di Azure Cloud

Untuk mengautentikasi ke Azure, tanpa rahasia, siapkan identitas terkelola. Pendekatan ini memungkinkan kode Anda untuk menggunakan DefaultAzureCredential.

Untuk menyiapkan identitas terkelola untuk cloud Azure:

Buat identitas terkelola
Mengatur Peran penyimpanan yang sesuai untuk identitas
Mengonfigurasi lingkungan Azure Anda agar berfungsi dengan identitas terkelola Anda

Ketika kedua tugas ini selesai, gunakan DefaultAzureCredential alih-alih string koneksi atau kunci akun. Pendekatan ini memungkinkan semua lingkungan Anda untuk menggunakan kode sumber yang sama persis tanpa masalah menggunakan rahasia dalam kode sumber.

Menggunakan DefaultAzureCredential dalam pengembangan lokal

Di lingkungan pengembangan lokal Anda, identitas Azure Anda (akun pribadi atau pengembangan yang Anda gunakan untuk masuk ke Portal Azure) perlu mengautentikasi ke Azure untuk menggunakan kode yang sama di runtime lokal dan cloud.

Kontainer: tambahkan dependensi yang diperlukan ke aplikasi Anda

Sertakan dependensi yang diperlukan untuk membuat token SAS kontainer.

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

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

Kontainer: mendapatkan variabel lingkungan

Nama akun Blob Storage dan nama kontainer adalah nilai minimum yang diperlukan untuk membuat token SAS kontainer:

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

Membuat SAS dengan DefaultAzureCredential

Langkah-langkah konseptual berikut diperlukan untuk membuat token SAS dengan DefaultAzureCredential:

Menyiapkan DefaultAzureCredential
- Pengembangan lokal - gunakan identitas pribadi dan tetapkan peran untuk penyimpanan
- Cloud Azure - membuat identitas terkelola
Gunakan DefaultAzureCredential untuk mendapatkan kunci delegasi pengguna dengan UserDelegationKey
Gunakan kunci delegasi pengguna untuk membuat token SAS dengan bidang yang sesuai dengan generateBlobSASQueryParameters

Kontainer: membuat token SAS dengan DefaultAzureCredential

Dengan identitas yang dikonfigurasi, gunakan kode berikut untuk membuat Token SAS delegasi pengguna untuk akun dan kontainer yang ada:

// 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;
}

Kode server sebelumnya membuat alur nilai untuk membuat token SAS kontainer:

Membuat BlobServiceClient dengan DefaultAzureCredential
Gunakan operasi blobServiceClient.getUserDelegationKey untuk membuat UserDelegationKey
Gunakan kunci untuk membuat string token SAS dengan generateBlobSASQueryParameters

Setelah Anda membuat token SAS kontainer, Anda dapat memberikannya kepada klien yang akan menggunakan token tersebut. Klien kemudian dapat menggunakannya untuk membuat daftar blob dalam kontainer. Contoh kode klien menunjukkan cara menguji SAS sebagai konsumen.

Kontainer: gunakan token SAS

Setelah token SAS kontainer dibuat, gunakan token tersebut. Sebagai contoh penggunaan token SAS, Anda:

Buat URL lengkap termasuk nama kontainer dan string kueri. String kueri adalah token SAS.
Buat ContainerClient dengan URL kontainer.
Gunakan klien: dalam contoh ini, daftar blob dalam kontainer dengan listBlobsFlat.

// 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: menambahkan dependensi yang diperlukan ke aplikasi Anda

Sertakan dependensi yang diperlukan untuk membuat n token SAS blob.

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

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

Blob: Mendapatkan variabel lingkungan

Nama akun Blob Storage dan nama kontainer adalah nilai minimum yang diperlukan untuk membuat token SAS blob:

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

Ketika Anda perlu membuat token SAS blob, Anda harus memiliki nama blob untuk membuat token SAS. Itu akan ditentukan sebelumnya seperti nama blob acak, nama blob yang dikirimkan pengguna, atau nama yang dihasilkan dari aplikasi Anda.

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

Blob: membuat token SAS dengan DefaultAzureCredential

Dengan identitas yang dikonfigurasi, gunakan kode berikut untuk membuat Token SAS delegasi pengguna untuk akun dan kontainer yang ada:

// 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;
}

Kode sebelumnya membuat alur nilai untuk membuat token SAS kontainer:

Membuat BlobServiceClient dengan DefaultAzureCredential
Gunakan operasi blobServiceClient.getUserDelegationKey untuk membuat UserDelegationKey
Gunakan kunci untuk membuat string token SAS. Jika nama blob tidak ditentukan dalam opsi, token SAS adalah token kontainer.

Setelah Anda membuat token SAS blob, Anda dapat memberikannya kepada klien yang akan menggunakan token tersebut. Klien kemudian dapat menggunakannya untuk mengunggah blob. Contoh kode klien menunjukkan cara menguji SAS sebagai konsumen.

Blob: gunakan token SAS

Setelah token SAS blob dibuat, gunakan token tersebut. Sebagai contoh penggunaan token SAS, Anda:

Buat URL lengkap termasuk nama kontainer, nama blob, dan string kueri. String kueri adalah token SAS.
Buat BlockBlobClient dengan URL kontainer.
Gunakan klien: dalam contoh ini, unggah blob dengan unggahan.

// 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);    
}

Lihat juga

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2024-08-05