Tworzenie tokenu SAS delegowania użytkownika za pomocą usługi Azure Blob Storage i języka JavaScript

Artykuł
10/18/2023

W tym artykule pokazano, jak utworzyć token SAS delegowania użytkownika w bibliotece klienta usługi Azure Blob Storage w wersji 12 dla języka JavaScript. Sygnatura dostępu współdzielonego delegowania użytkowników, wprowadzona w wersji 2018-11-09, jest zabezpieczona przy użyciu poświadczeń firmy Microsoft Entra i jest obsługiwana tylko dla usługi Blob:

Udzielanie dostępu do istniejącego kontenera.
Udzielanie dostępu do tworzenia, używania i usuwania obiektów blob.

Aby utworzyć sygnaturę dostępu współdzielonego delegowania użytkownika, klient musi mieć uprawnienia do wywoływania operacji blobServiceClient.getUserDelegationKey . Klucz zwracany przez tę operację jest używany do podpisywania sygnatury dostępu współdzielonego delegowania użytkownika. Podmiot zabezpieczeń, który wywołuje tę operację, musi mieć przypisaną rolę RBAC obejmującą wartość Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey/action.

Uprawnienia przyznane klientowi, który posiada sygnaturę dostępu współdzielonego, są skrzyżowaniem uprawnień, które zostały przyznane podmiotowi zabezpieczeń, który zażądał klucza delegowania użytkownika i uprawnieniami, które zostały przyznane zasobowi na token sas w polu podpisanych uprawnień (sp). Jeśli uprawnienie przyznane podmiotowi zabezpieczeń za pośrednictwem kontroli dostępu opartej na rolach nie zostanie również przyznane w tokenie SAS, to uprawnienie nie zostanie przyznane klientowi, który próbuje uzyskać dostęp do zasobu za pomocą sygnatury dostępu współdzielonego.

Przykładowe fragmenty kodu są dostępne w usłudze GitHub jako pliki Runnable Node.js.

Kod źródłowy biblioteki źródłowej interfejsu API package (npm)Samples | API Reference | Code | (Dokumentacja interfejsu API pakietu (npm) | Prześlij opinię

Najlepsze rozwiązania dotyczące tokenów SAS delegowania użytkowników

Ponieważ każda osoba mająca token SAS może używać go do uzyskiwania dostępu do kontenera i obiektów blob, należy zdefiniować token SAS z najbardziej restrykcyjnymi uprawnieniami, które nadal zezwalają tokenowi na wykonywanie wymaganych zadań.

Najlepsze rozwiązania dotyczące tokenów SAS

Korzystanie z wartości DefaultAzureCredential w chmurze platformy Azure

Aby uwierzytelnić się na platformie Azure, bez wpisów tajnych, skonfiguruj tożsamość zarządzaną. Dzięki temu kod może używać wartości DefaultAzureCredential.

Aby skonfigurować tożsamość zarządzaną dla chmury platformy Azure:

Tworzenie tożsamości zarządzanej
Ustawianie odpowiednich ról magazynu dla tożsamości
Konfigurowanie środowiska platformy Azure do pracy z tożsamością zarządzaną

Po zakończeniu tych dwóch zadań użyj wartości DefaultAzureCredential zamiast parametry połączenia lub klucza konta. Dzięki temu wszystkie środowiska mogą używać dokładnie tego samego kodu źródłowego bez konieczności używania wpisów tajnych w kodzie źródłowym.

Użyj wartości DefaultAzureCredential w programowania lokalnego

W lokalnym środowisku projektowym tożsamość platformy Azure (osobiste lub konto programistyczne używane do logowania się w witrynie Azure Portal) musi uwierzytelniać się na platformie Azure , aby używać tego samego kodu w środowiskach uruchomieniowych lokalnych i w chmurze.

Kontener: dodawanie wymaganych zależności do aplikacji

Uwzględnij wymagane zależności, aby utworzyć token SAS kontenera.

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

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

Kontener: pobieranie zmiennych środowiskowych

Nazwa konta usługi Blob Storage i nazwa kontenera są minimalnymi wymaganymi wartościami do utworzenia tokenu SAS kontenera:

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

Tworzenie sygnatury dostępu współdzielonego z wartością DefaultAzureCredential

Do utworzenia tokenu SYGNATURy dostępu współdzielonego przy użyciu polecenia DefaultAzureCredential wymagane są następujące czynności koncepcyjne:

Konfigurowanie wartości domyślnejAzureCredential
- Programowanie lokalne — używanie tożsamości osobistej i ustawianie ról dla magazynu
- Chmura platformy Azure — tworzenie tożsamości zarządzanej
Użyj wartości DefaultAzureCredential, aby uzyskać klucz delegowania użytkownika za pomocą elementu UserDelegationKey
Użyj klucza delegowania użytkownika, aby skonstruować token SAS z odpowiednimi polami z parametrami generateBlobSASQueryParameters

Kontener: tworzenie tokenu SAS za pomocą polecenia DefaultAzureCredential

Po skonfigurowaniu tożsamości użyj następującego kodu, aby utworzyć token SAS delegowania użytkownika dla istniejącego konta i kontenera:

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

Powyższy kod serwera tworzy przepływ wartości w celu utworzenia tokenu SAS kontenera:

Tworzenie obiektu BlobServiceClient przy użyciu elementu DefaultAzureCredential
Użyj operacji blobServiceClient.getUserDelegationKey, aby utworzyć klucz UserDelegationKey
Użyj klucza, aby utworzyć ciąg tokenu SAS z ciągiem generateBlobSASQueryParameters

Po utworzeniu tokenu SAS kontenera możesz podać go klientowi, który będzie używać tokenu. Klient może następnie użyć go do wyświetlenia listy obiektów blob w kontenerze. Przykład kodu klienta pokazuje, jak przetestować sygnaturę dostępu współdzielonego jako odbiorcę.

Kontener: użyj tokenu SAS

Po utworzeniu tokenu SAS kontenera użyj tokenu. Przykład użycia tokenu SAS:

Utwórz pełny adres URL, w tym nazwę kontenera i ciąg zapytania. Ciąg zapytania jest tokenem SAS.
Utwórz kontenerClient przy użyciu adresu URL kontenera.
Użyj klienta: w tym przykładzie wyświetl listę obiektów blob w kontenerze z 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}`);
    }    
}

Obiekt blob: dodawanie wymaganych zależności do aplikacji

Uwzględnij wymagane zależności, aby utworzyć n token SAS obiektu blob.

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

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

Obiekt blob: pobieranie zmiennych środowiskowych

Nazwa konta usługi Blob Storage i nazwa kontenera są minimalnymi wymaganymi wartościami do utworzenia tokenu SAS obiektu blob:

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

Jeśli musisz utworzyć token SAS obiektu blob, musisz mieć nazwę obiektu blob, aby utworzyć token SAS. Będzie to wstępnie określone, takie jak losowa nazwa obiektu blob, nazwa przesłanego przez użytkownika obiektu blob lub nazwa wygenerowana z aplikacji.

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

Obiekt blob: tworzenie tokenu SAS za pomocą polecenia DefaultAzureCredential

Po skonfigurowaniu tożsamości użyj następującego kodu, aby utworzyć token SAS delegowania użytkownika dla istniejącego konta i kontenera:

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

Powyższy kod tworzy przepływ wartości w celu utworzenia tokenu SAS kontenera:

Tworzenie obiektu BlobServiceClient za pomocą polecenia DefaultAzureCredential
Użyj operacji blobServiceClient.getUserDelegationKey, aby utworzyć klucz UserDelegationKey
Użyj klucza, aby utworzyć ciąg tokenu SYGNATURY dostępu współdzielonego. Jeśli nazwa obiektu blob nie została określona w opcjach, token SAS jest tokenem kontenera.

Po utworzeniu tokenu SAS obiektu blob możesz podać go klientowi, który będzie używać tokenu. Klient może następnie użyć go do przekazania obiektu blob. Przykład kodu klienta pokazuje, jak przetestować sygnaturę dostępu współdzielonego jako odbiorcę.

Obiekt blob: użyj tokenu SAS

Po utworzeniu tokenu SAS obiektu blob użyj tokenu. Przykład użycia tokenu SAS:

Utwórz pełny adres URL, w tym nazwę kontenera, nazwę obiektu blob i ciąg zapytania. Ciąg zapytania jest tokenem SAS.
Utwórz obiekt BlockBlobClient przy użyciu adresu URL kontenera.
Użyj klienta: w tym przykładzie przekaż obiekt blob z przekazywaniem.

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

Udostępnij za pośrednictwem