Aanbevolen procedures voor verificatie met de Azure Identity-bibliotheek voor JavaScript

2025-05-28

Dit artikel bevat richtlijnen voor het maximaliseren van de prestaties en betrouwbaarheid van uw JavaScript- en TypeScript-apps bij het verifiëren van Azure-services. Om optimaal gebruik te maken van de Azure Identity-bibliotheek voor JavaScript, is het belangrijk om inzicht te krijgen in mogelijke problemen en beperkingstechnieken.

Deterministische referenties gebruiken in productieomgevingen

DefaultAzureCredential is de meest benaderbare manier om aan de slag te gaan met de Azure Identity-bibliotheek, maar dat gemak introduceert ook bepaalde compromissen. Met name kan niet vooraf worden gegarandeerd welke specifieke referentie in de keten zal slagen en voor aanvraagverificatie zal worden gebruikt. In een productieomgeving kan deze onvoorspelbaarheid aanzienlijke en soms subtiele problemen veroorzaken.

Denk bijvoorbeeld aan de volgende hypothetische reeks gebeurtenissen:

Het beveiligingsteam van een organisatie verplicht alle apps om beheerde identiteit te gebruiken om te verifiëren bij Azure-resources.
Al maanden gebruikt een JavaScript-app, gehost op een Azure Virtual Machine (VM), DefaultAzureCredential om te verifiëren via een beheerde identiteit.
Zonder het ondersteuningsteam te vertellen, installeert een ontwikkelaar de Azure CLI op die VM en voert de az login opdracht uit om te verifiëren bij Azure.
Vanwege deze nieuwe afzonderlijke configuratiewijziging in de Azure-omgeving begint verificatie via de oorspronkelijke beheerde identiteit onverwacht te mislukken.
DefaultAzureCredential slaat de mislukte ManagedIdentityCredential over en zoekt naar de volgende beschikbare referentie, die AzureCliCredentialis.
De toepassing gaat de Azure CLI-referenties gebruiken in plaats van de beheerde identiteit, wat kan mislukken of leiden tot onverwachte uitbreiding of vermindering van bevoegdheden.

Als u dit soort subtiele problemen of stille fouten in productie-apps wilt voorkomen, vervangt u DefaultAzureCredential door een specifieke TokenCredential-implementatie, zoals ManagedIdentityCredential. Raadpleeg de documentatie van de Azure Identity-clientbibliotheek voor beschikbare identiteitsgegevens.

Denk bijvoorbeeld aan de volgende DefaultAzureCredential configuratie in een Express.js-project:

JavaScript
TypeScript

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";
import { BlobServiceClient } from "@azure/storage-blob";

const credential = new DefaultAzureCredential();

const secretClient = new SecretClient("https://keyVaultName.vault.azure.net", credential);
const blobServiceClient = new BlobServiceClient(
  "https://storageAccountName.blob.core.windows.net",
  credential
);

Wijzig de voorgaande code om een referentie te selecteren op basis van de omgeving waarin de app wordt uitgevoerd:

import { AzureDeveloperCliCredential, ManagedIdentityCredential, ChainedTokenCredential, 
         AzureCliCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";
import { BlobServiceClient } from "@azure/storage-blob";

let credential;

// In production, use only ManagedIdentityCredential
if (process.env.NODE_ENV === 'production') {
  // For user-assigned managed identity, provide the client ID
  credential = new ManagedIdentityCredential(process.env.AZURE_CLIENT_ID);
}
// In development, use a chain of credentials appropriate for local work
else {
  credential = new ChainedTokenCredential(
    new AzureCliCredential(),
    new AzureDeveloperCliCredential()
  );
}

// Initialize Key Vault client
const secretClient = new SecretClient("https://keyVaultName.vault.azure.net", credential);

// Initialize Blob Storage client
const blobServiceClient = new BlobServiceClient(
  "https://storageAccountName.blob.core.windows.net",
  credential
);

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";
import { BlobServiceClient } from "@azure/storage-blob";

const credential = new DefaultAzureCredential();

const secretClient = new SecretClient("https://keyVaultName.vault.azure.net", credential);
const blobServiceClient = new BlobServiceClient(
  "https://storageAccountName.blob.core.windows.net",
  credential
);

Wijzig de voorgaande code om een referentie te selecteren op basis van de omgeving waarin de app wordt uitgevoerd:

import { AzureDeveloperCliCredential, ManagedIdentityCredential, ChainedTokenCredential, 
         AzureCliCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";
import { BlobServiceClient } from "@azure/storage-blob";

let credential;

// In production, use only ManagedIdentityCredential
if (process.env.NODE_ENV === 'production') {
  // For user-assigned managed identity, provide the client ID
  credential = new ManagedIdentityCredential(process.env.AZURE_CLIENT_ID);
}
// In development, use a chain of credentials appropriate for local work
else {
  credential = new ChainedTokenCredential(
    new AzureCliCredential(),
    new AzureDeveloperCliCredential()
  );
}

// Initialize Key Vault client
const secretClient = new SecretClient("https://keyVaultName.vault.azure.net", credential);

// Initialize Blob Storage client
const blobServiceClient = new BlobServiceClient(
  "https://storageAccountName.blob.core.windows.net",
  credential
);

In dit voorbeeld wordt alleen ManagedIdentityCredential gebruikt in productie. De authenticatiebehoeften van de lokale ontwikkelomgeving worden vervolgens verwerkt door de reeks referenties die zijn gedefinieerd in de else-clausule.

Instances van inloggegevens opnieuw gebruiken

Gebruik waar mogelijk referentiegegevens opnieuw om de veerkracht van de app te verbeteren en het aantal aanvragen voor toegangstokens aan Microsoft Entra ID te verminderen. Wanneer een referentie opnieuw wordt gebruikt, wordt geprobeerd een token op te halen uit de app-tokencache die wordt beheerd door de onderliggende MSAL-afhankelijkheid. Zie tokencaching in de Azure Identity-clientbibliotheekvoor meer informatie.

Het cachegedrag van tokens verschilt tussen browser- en Node.js omgevingen. In Node.js toepassingen worden tokens standaard in het cachegeheugen opgeslagen. Dit betekent dat de cache verloren gaat wanneer de toepassing opnieuw wordt opgestart. In browsertoepassingen kunnen tokens worden bewaard in browseropslag (localStorage of sessionStorage) afhankelijk van de verificatiestroom en configuratie. Inzicht in deze verschillen is belangrijk bij het implementeren van strategieën voor hergebruik van referenties voor verschillende toepassingstypen.

Belangrijk

Een druk gebruikte app die geen referenties hergebruikt, kan HTTP 429-throttlingreacties van Microsoft Entra ID tegenkomen, wat kan leiden tot app-storingen.

De aanbevolen strategie voor het hergebruik van referenties verschilt per toepassingsframework.

JavaScript
TypeScript

Als u referenties opnieuw wilt gebruiken in JavaScript-toepassingen, maakt u één referentie-exemplaar en gebruikt u deze voor alle clientobjecten:

import { DefaultAzureCredential, ManagedIdentityCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";
import { BlobServiceClient } from "@azure/storage-blob";

// Create a single credential instance
const credential = process.env.NODE_ENV === 'production'
  ? new ManagedIdentityCredential(process.env.AZURE_CLIENT_ID)
  : new DefaultAzureCredential();

// Reuse the credential across different client objects
const secretClient = new SecretClient("https://keyVaultName.vault.azure.net", credential);
const blobServiceClient = new BlobServiceClient(
  "https://storageAccountName.blob.core.windows.net",
  credential
);

In Express.js toepassingen kunt u de referentie opslaan in app-instellingen en deze openen in uw route-handlers:

import express from "express";
import { DefaultAzureCredential, ManagedIdentityCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";
import { BlobServiceClient } from "@azure/storage-blob";

const app = express();

// Create a single credential instance at app startup
app.locals.credential = process.env.NODE_ENV === 'production'
  ? new ManagedIdentityCredential(process.env.AZURE_CLIENT_ID)
  : new DefaultAzureCredential();

// Reuse the credential in route handlers
app.get('/api/secrets/:secretName', async (req, res) => {
  const secretClient = new SecretClient(
    "https://keyVaultName.vault.azure.net", 
    req.app.locals.credential
  );
  
  try {
    const secret = await secretClient.getSecret(req.params.secretName);
    res.json({ name: secret.name, value: secret.value });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

// Add this route to the existing Express app
app.get('/api/blobs/:containerName', async (req, res) => {
  const blobServiceClient = new BlobServiceClient(
    "https://storageAccountName.blob.core.windows.net", 
    req.app.locals.credential
  );
  
  try {
    // Get reference to a container
    const containerClient = blobServiceClient.getContainerClient(req.params.containerName);
    
    // List all blobs in the container
    const blobs = [];
    for await (const blob of containerClient.listBlobsFlat()) {
      blobs.push({
        name: blob.name,
        contentType: blob.properties.contentType,
        size: blob.properties.contentLength,
        lastModified: blob.properties.lastModified
      });
    }
    
    res.json({ containerName: req.params.containerName, blobs });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(3000, () => console.log('Server running on port 3000'));

Als u referenties opnieuw wilt gebruiken in TypeScript-toepassingen, maakt u één referentie-exemplaar en gebruikt u deze voor alle clientobjecten:

import { DefaultAzureCredential, ManagedIdentityCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";
import { BlobServiceClient } from "@azure/storage-blob";

// Create a single credential instance
const credential = process.env.NODE_ENV === 'production'
  ? new ManagedIdentityCredential(process.env.AZURE_CLIENT_ID as string)
  : new DefaultAzureCredential();

// Reuse the credential across different client objects
const secretClient = new SecretClient("https://keyVaultName.vault.azure.net", credential);
const blobServiceClient = new BlobServiceClient(
  "https://storageAccountName.blob.core.windows.net",
  credential
);

In Express.js toepassingen kunt u de referentie opslaan in app-instellingen en deze openen in uw route-handlers:

import express from "express";
import { DefaultAzureCredential, ManagedIdentityCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";
import { BlobServiceClient } from "@azure/storage-blob";

const app = express();

// Create a single credential instance at app startup
app.locals.credential = process.env.NODE_ENV === 'production'
  ? new ManagedIdentityCredential(process.env.AZURE_CLIENT_ID)
  : new DefaultAzureCredential();

// Reuse the credential in route handlers
app.get('/api/secrets/:secretName', async (req, res) => {
  const secretClient = new SecretClient(
    "https://keyVaultName.vault.azure.net", 
    req.app.locals.credential
  );
  
  try {
    const secret = await secretClient.getSecret(req.params.secretName);
    res.json({ name: secret.name, value: secret.value });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

// Add this route to the existing Express app
app.get('/api/blobs/:containerName', async (req, res) => {
  const blobServiceClient = new BlobServiceClient(
    "https://storageAccountName.blob.core.windows.net", 
    req.app.locals.credential
  );
  
  try {
    // Get reference to a container
    const containerClient = blobServiceClient.getContainerClient(req.params.containerName);
    
    // List all blobs in the container
    const blobs = [];
    for await (const blob of containerClient.listBlobsFlat()) {
      blobs.push({
        name: blob.name,
        contentType: blob.properties.contentType,
        size: blob.properties.contentLength,
        lastModified: blob.properties.lastModified
      });
    }
    
    res.json({ containerName: req.params.containerName, blobs });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(3000, () => console.log('Server running on port 3000'));

Begrijpen wanneer tokenlevensduur en cachelogica nodig zijn

Als u een Azure Identity Library-referentie gebruikt buiten de context van een Azure SDK-clientbibliotheek, wordt het uw verantwoordelijkheid om de levensduur van tokens en het cachegedrag in uw app te beheren.

De refreshAfterTimestamp eigenschap in AccessToken, die een hint biedt aan consumenten wanneer het vernieuwen van tokens kan worden geprobeerd, wordt automatisch gebruikt door Azure SDK-clientbibliotheken die afhankelijk zijn van de Azure Core-bibliotheek om het token te vernieuwen. Voor direct gebruik van azure Identity-bibliotheekreferenties die ondersteuning bieden voor tokencaching, wordt de onderliggende MSAL-cache automatisch proactief vernieuwd wanneer de refreshAfterTimestamp tijd plaatsvindt. Met dit ontwerp kan de clientcode TokenCredential.getToken() aanroepen telkens wanneer een token nodig is en de vernieuwing delegeren aan de bibliotheek.

Als u alleen TokenCredential.getToken() wilt aanroepen wanneer dat nodig is, bekijkt u de refreshAfterTimestamp datum en probeert u het token na die tijd proactief te vernieuwen. De specifieke implementatie is aan de klant.

Inzicht in de strategie voor opnieuw proberen van beheerde identiteit

Met de Azure Identity-bibliotheek voor JavaScript kunt u zich verifiëren via een beheerde identiteit met ManagedIdentityCredential. De manier waarop u ManagedIdentityCredential gebruikt, beïnvloedt de toegepaste retry-strategie:

Bij gebruik via DefaultAzureCredential, worden er geen nieuwe pogingen gedaan wanneer de eerste poging tot het verkrijgen van een token mislukt of een korte time-out oploopt. Dit is de minst veerkrachtige optie omdat deze is geoptimaliseerd om snel te falen voor een efficiënte interne ontwikkelingscyclus.
Andere benaderingen, zoals ChainedTokenCredential of ManagedIdentityCredential direct:
- Het tijdsinterval tussen nieuwe pogingen begint bij 0,8 seconden en er worden standaard vijf nieuwe pogingen geprobeerd. Deze optie is geoptimaliseerd voor tolerantie, maar introduceert mogelijk ongewenste vertragingen in de interne ontwikkelingslus.
- Als u een van de standaardinstellingen voor opnieuw proberen wilt wijzigen, gebruikt u de eigenschap retryOptions voor de parameter opties. Probeer het bijvoorbeeld maximaal drie keer opnieuw, met een begininterval van 0,5 seconden:

JavaScript
TypeScript

import { ManagedIdentityCredential } from "@azure/identity";

const credential = new ManagedIdentityCredential(
  process.env.AZURE_CLIENT_ID, // For user-assigned managed identity
  {
    retryOptions: {
      maxRetries: 3,           // Maximum number of retry attempts
      retryDelayInMs: 500,     // Initial delay between retries (in milliseconds)
      maxRetryDelayInMs: 5000  // Maximum delay between retries (in milliseconds)
    }
  }
);

import { ManagedIdentityCredential } from "@azure/identity";

const credential = new ManagedIdentityCredential(
  process.env.AZURE_CLIENT_ID as string, // For user-assigned managed identity
  {
    retryOptions: {
      maxRetries: 3,           // Maximum number of retry attempts
      retryDelayInMs: 500,     // Initial delay between retries (in milliseconds)
      maxRetryDelayInMs: 5000  // Maximum delay between retries (in milliseconds)
    }
  }
);

Zie een van de volgende opties die voortkomen uit TokenCredentialOptions voor meer informatie over het aanpassen van opnieuw poging beleid voor beheerde identiteiten:

Feedback

Is deze pagina nuttig?