Vytvoření tokenu SAS delegování uživatele pomocí služby Azure Blob Storage a JavaScriptu

Článek
10/31/2024

V tomto článku se dozvíte, jak vytvořit token SAS delegování uživatele v klientské knihovně služby Azure Blob Storage v12 pro JavaScript. Sas delegování uživatele zavedený ve verzi 2018-11-09 je zabezpečený pomocí přihlašovacích údajů Microsoft Entra a podporuje se pouze pro službu Blob Service:

Udělte přístup k existujícímu kontejneru.
Udělte přístup k vytváření, používání a odstraňování objektů blob.

Pokud chcete vytvořit SAS delegování uživatele, musí mít klient oprávnění k volání operace blobServiceClient.getUserDelegationKey . Klíč vrácený touto operací slouží k podepsání SAS delegování uživatele. Objekt zabezpečení, který tuto operaci volá, musí mít přiřazenou roli RBAC, která zahrnuje Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey/action.

Oprávnění udělená klientovi, který má SAS, jsou průnikem oprávnění udělených objektu zabezpečení, který požadoval klíč delegování uživatele a oprávnění udělená prostředku v tokenu SAS v poli podepsaná oprávnění (sp). Pokud není u tokenu SAS udělené oprávnění udělené instančnímu objektu zabezpečení prostřednictvím RBAC, nebude toto oprávnění uděleno klientovi, který se pokusí použít SAS pro přístup k prostředku.

Ukázkové fragmenty kódu jsou k dispozici na GitHubu jako spustitelné Node.js soubory.

Package (npm) | Samples | API reference | Library source code | Give Feedback

Osvědčené postupy pro tokeny SAS delegování uživatelů

Vzhledem k tomu, že každý, kdo má token SAS, ho může použít pro přístup ke kontejneru a objektům blob, měli byste definovat token SAS s nejvíce omezujícími oprávněními, která token stále umožňují dokončit požadované úlohy.

Osvědčené postupy pro tokeny SAS

Použití defaultAzureCredential v Azure Cloudu

Pokud se chcete ověřit v Azure bez tajných kódů, nastavte spravovanou identitu. Tento přístup umožňuje vašemu kódu používat DefaultAzureCredential.

Nastavení spravované identity pro cloud Azure:

Vytvoření spravované identity
Nastavení odpovídajících rolí úložiště pro identitu
Konfigurace prostředí Azure pro práci se spravovanou identitou

Po dokončení těchto dvou úkolů použijte místo klíče připojovací řetězec nebo klíče účtu defaultAzureCredential. Tento přístup umožňuje všem vašim prostředím používat stejný zdrojový kód bez problému s používáním tajných kódů ve zdrojovém kódu.

Použití DefaultAzureCredential v místním vývoji

V místním vývojovém prostředí musí vaše identita Azure (váš osobní nebo vývojový účet, který používáte pro přihlášení k webu Azure Portal), ověřit v Azure, aby používala stejný kód v místních a cloudových modulech runtime.

Kontejner: Přidání požadovaných závislostí do aplikace

Zahrňte požadované závislosti pro vytvoření tokenu SAS kontejneru.

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

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

Kontejner: Získání proměnných prostředí

Název účtu služby Blob Storage a název kontejneru jsou minimální požadované hodnoty pro vytvoření tokenu SAS kontejneru:

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

Vytvoření SAS s defaultAzureCredential

K vytvoření tokenu SAS s defaultAzureCredential se vyžadují následující koncepční kroky:

Nastavení defaultAzureCredential
- Místní vývoj – použití osobní identity a nastavení rolí pro úložiště
- Cloud Azure – vytvoření spravované identity
Použití DefaultAzureCredential k získání klíče delegování uživatele pomocí UserDelegationKey
Použití klíče delegování uživatele k vytvoření tokenu SAS s příslušnými poli pomocí generateBlobSASQueryParameters

Kontejner: Vytvoření tokenu SAS pomocí DefaultAzureCredential

S nakonfigurovanou identitou vytvořte pomocí následujícího kódu token SAS delegování uživatele pro existující účet a kontejner:

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

Předchozí kód serveru vytvoří tok hodnot pro vytvoření tokenu SAS kontejneru:

Vytvoření objektu BlobServiceClient pomocí defaultAzureCredential
Vytvoření klíče UserDelegationKey pomocí operace blobServiceClient.getUserDelegationKey
Použití klíče k vytvoření řetězce tokenu SAS pomocí generateBlobSASQueryParameters

Jakmile vytvoříte token SAS kontejneru, můžete ho poskytnout klientovi, který token bude využívat. Klient ho pak může použít k výpisu objektů blob v kontejneru. Příklad kódu klienta ukazuje, jak otestovat SAS jako příjemce.

Kontejner: Použití tokenu SAS

Po vytvoření tokenu SAS kontejneru použijte token. Jako příklad použití tokenu SAS:

Vytvořte úplnou adresu URL včetně názvu kontejneru a řetězce dotazu. Řetězec dotazu je token SAS.
Vytvořte ContainerClient s adresou URL kontejneru.
Použijte klienta: v tomto příkladu vypíše objekty blob v kontejneru pomocí 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}`);
    }    
}

Objekt blob: Přidání požadovaných závislostí do aplikace

Zahrňte požadované závislosti pro vytvoření n tokenu SAS objektu blob.

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

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

Objekt blob: získání proměnných prostředí

Název účtu služby Blob Storage a název kontejneru jsou minimální požadované hodnoty pro vytvoření tokenu SAS objektu blob:

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

Pokud potřebujete vytvořit token SAS objektu blob, musíte mít název objektu blob pro vytvoření tokenu SAS. To bude předem určené, například náhodný název objektu blob, název objektu blob odeslaný uživatelem nebo název vygenerovaný z vaší aplikace.

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

Objekt blob: Vytvoření tokenu SAS pomocí DefaultAzureCredential

S nakonfigurovanou identitou vytvořte pomocí následujícího kódu token SAS delegování uživatele pro existující účet a kontejner:

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

Předchozí kód vytvoří tok hodnot pro vytvoření tokenu SAS kontejneru:

Vytvoření objektu BlobServiceClient pomocí defaultAzureCredential
Vytvoření klíče UserDelegationKey pomocí operace blobServiceClient.getUserDelegationKey
Pomocí klíče vytvořte řetězec tokenu SAS. Pokud v možnostech nebyl zadán název objektu blob, token SAS je token kontejneru.

Jakmile vytvoříte token SAS objektu blob, můžete ho poskytnout klientovi, který token bude využívat. Klient ho pak může použít k nahrání objektu blob. Příklad kódu klienta ukazuje, jak otestovat SAS jako příjemce.

Objekt blob: Použití tokenu SAS

Po vytvoření tokenu SAS objektu blob použijte token. Jako příklad použití tokenu SAS:

Vytvořte úplnou adresu URL, včetně názvu kontejneru, názvu objektu blob a řetězce dotazu. Řetězec dotazu je token SAS.
Vytvořte BlockBlobClient s adresou URL kontejneru.
Použijte klienta: v tomto příkladu nahrajte objekt blob s nahráním.

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

Sdílet prostřednictvím