Skapa en SAS-token för användardelegering med Azure Blob Storage och JavaScript

Artikel
08/05/2024

Den här artikeln visar hur du skapar en SAS-token för användardelegering i Azure Blob Storage-klientbiblioteket v12 för JavaScript. En SAS för användardelegering, som introducerades med version 2018-11-09, skyddas med Microsoft Entra-autentiseringsuppgifter och stöds endast för Blob-tjänsten för att:

Bevilja åtkomst till en befintlig container.
Bevilja åtkomst för att skapa, använda och ta bort blobar.

Om du vill skapa en SAS för användardelegering måste en klient ha behörighet att anropa åtgärden blobServiceClient.getUserDelegationKey . Nyckeln som returneras av den här åtgärden används för att signera SAS för användardelegering. Säkerhetsobjektet som anropar den här åtgärden måste tilldelas en RBAC-roll som innehåller åtgärden Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey/.

Behörigheterna som beviljas till en klient som har SAS är skärningspunkten mellan de behörigheter som har beviljats till säkerhetsobjektet som begärde användardelegeringsnyckeln och de behörigheter som beviljats resursen på SAS-token i fältet signerade behörigheter (sp). Om en behörighet som beviljas säkerhetsobjektet via RBAC inte också beviljas för SAS-token beviljas inte den behörigheten till klienten som försöker använda SAS för att komma åt resursen.

Exempelkodfragmenten är tillgängliga i GitHub som körbara Node.js filer.

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

Metodtips för SAS-token för användardelegering

Eftersom alla med SAS-token kan använda den för att komma åt containern och blobarna bör du definiera SAS-token med de mest restriktiva behörigheter som fortfarande tillåter token att slutföra de uppgifter som krävs.

Metodtips för SAS-token

Använda StandardAzureCredential i Azure Cloud

Konfigurera hanterad identitet för att autentisera till Azure utan hemligheter. Med den här metoden kan din kod använda DefaultAzureCredential.

Så här konfigurerar du hanterad identitet för Azure-molnet:

Skapa en hanterad identitet
Ange lämpliga lagringsroller för identiteten
Konfigurera din Azure-miljö så att den fungerar med din hanterade identitet

När de här två uppgifterna är klara använder du StandardAzureCredential i stället för en anslutningssträng- eller kontonyckel. Med den här metoden kan alla dina miljöer använda exakt samma källkod utan problem med att använda hemligheter i källkoden.

Använd StandardAzureCredential i lokal utveckling

I din lokala utvecklingsmiljö måste din Azure-identitet (ditt personliga konto eller utvecklingskonto som du använder för att logga in på Azure Portal) autentisera till Azure för att använda samma kod i lokala och molnbaserade körningar.

Container: lägga till nödvändiga beroenden i ditt program

Inkludera de beroenden som krävs för att skapa en CONTAINER SAS-token.

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

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

Container: hämta miljövariabler

Namnet på Blob Storage-kontot och containernamnet är de minsta värden som krävs för att skapa en CONTAINER SAS-token:

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

Skapa en SAS med DefaultAzureCredential

Följande konceptuella steg krävs för att skapa en SAS-token med DefaultAzureCredential:

Konfigurera DefaultAzureCredential
- Lokal utveckling – använd personlig identitet och ange roller för lagring
- Azure-moln – skapa hanterad identitet
Använd DefaultAzureCredential för att hämta användardelegeringsnyckeln med UserDelegationKey
Använd användardelegeringsnyckeln för att konstruera SAS-token med lämpliga fält med generateBlobSASQueryParameters

Container: skapa SAS-token med DefaultAzureCredential

När identiteten är konfigurerad använder du följande kod för att skapa SAS-token för användardelegering för ett befintligt konto och en container:

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

Föregående serverkod skapar ett flöde med värden för att skapa containerns SAS-token:

Skapa BlobServiceClient med StandardAzureCredential
Använd åtgärden blobServiceClient.getUserDelegationKey för att skapa en UserDelegationKey
Använd nyckeln för att skapa SAS-tokensträngen med generateBlobSASQueryParameters

När du har skapat CONTAINER SAS-token kan du ange den för klienten som ska använda token. Klienten kan sedan använda den för att lista blobarna i en container. Ett exempel på klientkod visar hur du testar SAS som konsument.

Container: använd SAS-token

När containerns SAS-token har skapats använder du token. Som ett exempel på hur du använder SAS-token kan du:

Skapa en fullständig URL, inklusive containernamn och frågesträng. Frågesträngen är SAS-token.
Skapa en ContainerClient med containerns URL.
Använd klienten: I det här exemplet listar du blobar i containern med 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: lägga till nödvändiga beroenden i ditt program

Inkludera nödvändiga beroenden för att skapa n blob-SAS-token.

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

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

Blob: hämta miljövariabler

Namnet på Blob Storage-kontot och containernamnet är de minsta värden som krävs för att skapa en BLOB SAS-token:

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

När du behöver skapa en BLOB SAS-token måste du ha blobnamnet för att skapa SAS-token. Det kommer att vara förutbestämt, till exempel ett slumpmässigt blobnamn, ett användarinskickat blobnamn eller ett namn som genererats från ditt program.

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

Blob: skapa SAS-token med DefaultAzureCredential

När identiteten är konfigurerad använder du följande kod för att skapa SAS-token för användardelegering för ett befintligt konto och en container:

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

Föregående kod skapar ett flöde med värden för att skapa containerns SAS-token:

Skapa BlobServiceClient med DefaultAzureCredential
Använd åtgärden blobServiceClient.getUserDelegationKey för att skapa en UserDelegationKey
Använd nyckeln för att skapa SAS-tokensträngen. Om blobnamnet inte angavs i alternativen är SAS-token en containertoken.

När du har skapat blob-SAS-token kan du ange den för klienten som ska använda token. Klienten kan sedan använda den för att ladda upp en blob. Ett exempel på klientkod visar hur du testar SAS som konsument.

Blob: använd SAS-token

När blob-SAS-token har skapats använder du token. Som ett exempel på hur du använder SAS-token kan du:

Skapa en fullständig URL, inklusive containernamn, blobnamn och frågesträng. Frågesträngen är SAS-token.
Skapa en BlockBlobClient med containerns URL.
Använd klienten: i det här exemplet laddar du upp blob med uppladdning.

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

Dela via