Delen via

Een SAS-token voor gebruikersdelegering maken met Azure Blob Storage en JavaScript

  • Artikel

In dit artikel leest u hoe u een SAS-token voor gebruikersdelegering maakt in de Azure Blob Storage-clientbibliotheek v12 voor JavaScript. Een SAS voor gebruikersdelegatie, geïntroduceerd met versie 2018-11-09, wordt beveiligd met Microsoft Entra-referenties en wordt alleen ondersteund voor de Blob-service voor:

  • Toegang verlenen tot een bestaande container.
  • Toegang verlenen tot het maken, gebruiken en verwijderen van blobs.

Als u een SAS voor gebruikersdelegatie wilt maken, moet een client gemachtigd zijn om de bewerking blobServiceClient.getUserDelegationKey aan te roepen. De sleutel die door deze bewerking wordt geretourneerd, wordt gebruikt om de SAS voor gebruikersdelegering te ondertekenen. Aan de beveiligingsprincipaal die deze bewerking aanroept, moet een RBAC-rol worden toegewezen die de Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey/action bevat.

De machtigingen die zijn verleend aan een client die de SAS bezit, zijn het snijpunt van de machtigingen die zijn verleend aan de beveiligingsprincipaal die de gebruikersdelegeringssleutel en de machtigingen die zijn verleend aan de resource op het SAS-token in het veld ondertekende machtigingen (SP). Als een machtiging die via RBAC aan de beveiligingsprincipaal wordt verleend, niet ook wordt verleend aan het SAS-token, wordt die machtiging niet verleend aan de client die de SAS probeert te gebruiken voor toegang tot de resource.

De voorbeeldcodefragmenten zijn beschikbaar in GitHub als runnable Node.js-bestanden.

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

Aanbevolen procedures voor SAS-tokens voor gebruikersdelegatie

Omdat iedereen met het SAS-token deze kan gebruiken voor toegang tot de container en blobs, moet u het SAS-token definiëren met de meest beperkende machtigingen waarmee het token nog steeds de vereiste taken kan uitvoeren.

Aanbevolen procedures voor SAS-tokens

De DefaultAzureCredential gebruiken in Azure Cloud

Als u zich wilt verifiëren bij Azure, zonder geheimen, moet u een beheerde identiteit instellen. Hierdoor kan uw code DefaultAzureCredential gebruiken.

Beheerde identiteit instellen voor de Azure-cloud:

  • Een beheerde identiteit maken
  • De juiste opslagrollen instellen voor de identiteit
  • Uw Azure-omgeving configureren voor gebruik met uw beheerde identiteit

Wanneer deze twee taken zijn voltooid, gebruikt u de DefaultAzureCredential in plaats van een verbindingsreeks- of accountsleutel. Hierdoor kunnen al uw omgevingen exact dezelfde broncode gebruiken zonder het probleem van het gebruik van geheimen in broncode.

De DefaultAzureCredential gebruiken in lokale ontwikkeling

In uw lokale ontwikkelomgeving moet uw Azure-identiteit (uw persoonlijke of ontwikkelingsaccount dat u gebruikt om u aan te melden bij Azure Portal) verifiëren bij Azure om dezelfde code in lokale en cloudruntimes te gebruiken.

Container: vereiste afhankelijkheden toevoegen aan uw toepassing

Neem de vereiste afhankelijkheden op om een SAS-token voor containers te maken.

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

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

Container: omgevingsvariabelen ophalen

De naam van het Blob Storage-account en de containernaam zijn de minimaal vereiste waarden voor het maken van een SAS-token voor containers:

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

Een SAS maken met DefaultAzureCredential

De volgende conceptuele stappen zijn vereist voor het maken van een SAS-token met DefaultAzureCredential:

  • DefaultAzureCredential instellen
    • Lokale ontwikkeling: persoonlijke identiteit gebruiken en rollen instellen voor opslag
    • Azure-cloud - beheerde identiteit maken
  • DefaultAzureCredential gebruiken om de gebruikersdelegatiesleutel op te halen met UserDelegationKey
  • Gebruik de gebruikersdelegatiesleutel om het SAS-token samen te stellen met de juiste velden met generateBlobSASQueryParameters

Container: SAS-token maken met DefaultAzureCredential

Als de identiteit is geconfigureerd, gebruikt u de volgende code om sas-token voor gebruikersdelegering te maken voor een bestaand account en een bestaande 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;
}

Met de voorgaande servercode wordt een stroom waarden gemaakt om het SAS-token van de container te maken:

Zodra u het SAS-token voor de container hebt gemaakt, kunt u het aan de client opgeven die het token verbruikt. De client kan deze vervolgens gebruiken om de blobs in een container weer te geven. Een voorbeeld van een clientcode laat zien hoe u de SAS als consument kunt testen.

Container: SAS-token gebruiken

Zodra het SAS-token voor de container is gemaakt, gebruikt u het token. Als voorbeeld van het gebruik van het SAS-token, gaat u als volgt te werk:

  • Maak een volledige URL, inclusief containernaam en queryreeks. De queryreeks is het SAS-token.
  • Maak een ContainerClient met de container-URL.
  • Gebruik de client: in dit voorbeeld vermeldt u blobs in de container met 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: vereiste afhankelijkheden toevoegen aan uw toepassing

Neem de vereiste afhankelijkheden op om een n blob SAS-token te maken.

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

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

Blob: omgevingsvariabelen ophalen

De naam van het Blob Storage-account en de containernaam zijn de minimaal vereiste waarden voor het maken van een BLOB SAS-token:

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

Wanneer u een BLOB SAS-token moet maken, moet u de blobnaam hebben om het SAS-token te maken. Dit wordt vooraf bepaald, zoals een willekeurige blobnaam, een door de gebruiker ingediende blobnaam of een naam die is gegenereerd op basis van uw toepassing.

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

Blob: SAS-token maken met DefaultAzureCredential

Als de identiteit is geconfigureerd, gebruikt u de volgende code om sas-token voor gebruikersdelegering te maken voor een bestaand account en een bestaande 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;
}

Met de voorgaande code wordt een stroom waarden gemaakt om het SAS-token van de container te maken:

Zodra u het BLOB SAS-token hebt gemaakt, kunt u dit aan de client opgeven die het token verbruikt. De client kan deze vervolgens gebruiken om een blob te uploaden. Een voorbeeld van een clientcode laat zien hoe u de SAS als consument kunt testen.

Blob: SAS-token gebruiken

Zodra het SAS-token voor de blob is gemaakt, gebruikt u het token. Als voorbeeld van het gebruik van het SAS-token, gaat u als volgt te werk:

  • Maak een volledige URL, inclusief containernaam, blobnaam en querytekenreeks. De queryreeks is het SAS-token.
  • Maak een BlockBlobClient met de container-URL.
  • Gebruik de client: upload in dit voorbeeld blob met uploaden.
// 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);    
}

Zie ook