Referentieketens in de Azure Identity-bibliotheek voor JavaScript

De Azure Identity-bibliotheek biedt referenties, openbare klassen die de TokenCredential- interface van de Azure Core-bibliotheek implementeren. Een autorisatiegegeven vertegenwoordigt een afzonderlijke verificatiestroom voor het verkrijgen van een toegangstoken van Microsoft Entra ID. Deze referenties kunnen worden gekoppeld om een geordende reeks verificatiemechanismen te vormen die moeten worden geprobeerd.

Hoe een gekoppelde referentie werkt

Tijdens runtime probeert een referentieketen te verifiëren met behulp van de eerste referentie van de reeks. Als deze referentie geen toegangstoken kan verkrijgen, wordt de volgende referentie in de reeks geprobeerd, enzovoort, totdat een toegangstoken is verkregen. In het volgende sequentiediagram ziet u dit gedrag:

Waarom referentieketens gebruiken

Een gekoppelde geloofsbrief kan de volgende voordelen bieden:

• Omgevingsbewustzijn: selecteert automatisch de meest geschikte referentie op basis van de omgeving waarin de app wordt uitgevoerd. Zonder deze code moet u als volgt code schrijven:

  import { 
      ManagedIdentityCredential, 
      AzureCliCredential 
  } from "@azure/identity";
  
  let credential;
  if (process.env.NODE_ENV === "production") {
      credential = new ManagedIdentityCredential();
  } else {
      credential = new AzureCliCredential();
  }
  

• Naadloze overgangen: uw app kan overstappen van lokale ontwikkeling naar uw faserings- of productieomgeving zonder verificatiecode te wijzigen.

• Verbeterde tolerantie: bevat een terugvalmechanisme dat overgaat naar de volgende inloggegevens wanneer de vorige geen toegangstoken verkrijgt.

Hoe een gekoppelde referentie te kiezen

Er zijn twee verschillende benaderingen voor het koppelen van referenties:

• Een keten afbreken: begin met een vooraf geconfigureerde keten en sluit uit wat u niet nodig hebt. Raadpleeg de sectie DefaultAzureCredential-overzicht voor deze aanpak.
• 'Bouw' een keten op: Begin met een lege keten en neem alleen op wat u nodig hebt. Zie de sectie ChainedTokenCredential-overzicht voor deze benadering.

Overzicht van DefaultAzureCredential

DefaultAzureCredential- is een specifiek, vooraf geconfigureerde keten van referenties. Het is ontworpen om veel omgevingen te ondersteunen, samen met de meest voorkomende verificatiestromen en ontwikkelhulpprogramma's. In grafische vorm ziet de onderliggende keten er als volgt uit:

De volgorde waarin DefaultAzureCredential referenties probeert.

In de eenvoudigste vorm kunt u de parameterloze versie van DefaultAzureCredential als volgt gebruiken:

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

// Acquire a credential object
const credential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
    `https://${storageAccountName}.blob.core.windows.net`,
    credential
);

Hoe pas je DefaultAzureCredential aan

In de volgende secties worden strategieën beschreven voor het beheren van welke referenties in de keten zijn opgenomen.

Een categorie referentietype uitsluiten

Als u alle Developer tool of Deployed service referenties wilt uitsluiten, stelt u de omgevingsvariabele AZURE_TOKEN_CREDENTIALSprod in op respectievelijk dev. Wanneer een waarde van prod wordt gebruikt, ziet de onderliggende referentieketen er als volgt uit:

Wanneer een waarde van dev wordt gebruikt, ziet de keten er als volgt uit:

Om ervoor te zorgen dat de omgevingsvariabele is gedefinieerd en ingesteld op een ondersteunde tekenreeks, stelt u de eigenschap AZURE_TOKEN_CREDENTIALS op:

const credential = new DefaultAzureCredential({ 
    requiredEnvVars: [ "AZURE_TOKEN_CREDENTIALS" ]
});

Een specifieke referentie gebruiken

Als u alle referenties behalve één wilt uitsluiten, stelt u de omgevingsvariabele AZURE_TOKEN_CREDENTIALS in op de naam van de referentie. U kunt bijvoorbeeld de keten beperken door deze DefaultAzureCredential in te stellen AzureCliCredential op AZURE_TOKEN_CREDENTIALS.AzureCliCredential De tekenreeksvergelijking wordt op een niet-hoofdlettergevoelige manier uitgevoerd. Geldige tekenreekswaarden voor de omgevingsvariabele zijn:

• AzureCliCredential
• AzureDeveloperCliCredential
• AzurePowerShellCredential
• EnvironmentCredential
• ManagedIdentityCredential
• VisualStudioCodeCredential
• WorkloadIdentityCredential

Om ervoor te zorgen dat de omgevingsvariabele is gedefinieerd en ingesteld op een ondersteunde tekenreeks, stelt u de eigenschap requiredEnvVars in op AZURE_TOKEN_CREDENTIALS:

const credential = new DefaultAzureCredential({ 
    requiredEnvVars: [ "AZURE_TOKEN_CREDENTIALS" ]
});

Overzicht ChainedTokenCredential

ChainedTokenCredential is een lege keten waaraan u referentiële gegevens toevoegt die passen bij de behoeften van uw app. Voorbeeld:

import { 
    ChainedTokenCredential, 
    AzureCliCredential, 
    VisualStudioCodeCredential 
} from "@azure/identity";

const credential = new ChainedTokenCredential(
    new AzureCliCredential(),
    new VisualStudioCodeCredential()
);

const blobServiceClient = new BlobServiceClient(
    `https://${storageAccountName}.blob.core.windows.net`,
    credential
);

In het voorgaande codevoorbeeld wordt een aangepaste inloggegevensketen gemaakt die bestaat uit twee ontwikkeltijd-inloggegevens. AzureCliCredential wordt eerst geprobeerd, gevolgd door VisualStudioCodeCredential, indien nodig. In grafische vorm ziet de keten er als volgt uit:

Gebruiksrichtlijnen voor DefaultAzureCredential

DefaultAzureCredential is ongetwijfeld de eenvoudigste manier om aan de slag te gaan met de Azure Identity-bibliotheek, maar dat gemak brengt ook nadelen met zich mee. Zodra u uw app in Azure hebt geïmplementeerd, moet u de verificatievereisten van de app begrijpen. Vervang daarom DefaultAzureCredential door een specifieke TokenCredential-implementatie, zoals ManagedIdentityCredential.

Dit is de reden waarom:

• Problemen met foutopsporing: wanneer de verificatie mislukt, kan het lastig zijn om fouten op te sporen en de foutopsporingsreferentie te identificeren. U moet logboekregistratie inschakelen om de voortgang te zien van de ene referentie naar de volgende en de succes-/foutstatus van elke referentie. Zie Fouten opsporen in een referentie voor meer informatie.
• Prestatieoverhead: het proces waarbij meerdere referenties opeenvolgend worden geprobeerd, kan leiden tot prestatieoverhead. Wanneer bijvoorbeeld een lokale ontwikkelcomputer wordt gebruikt, is een beheerde identiteit niet beschikbaar. ManagedIdentityCredential mislukt daarom altijd in de lokale ontwikkelomgeving.
• Onvoorspelbaar gedrag: DefaultAzureCredential controleert op de aanwezigheid van bepaalde omgevingsvariabelen. Het is mogelijk dat iemand deze omgevingsvariabelen kan toevoegen of wijzigen op systeemniveau op de hostcomputer. Deze wijzigingen zijn globaal van toepassing en wijzigen daarom het gedrag van DefaultAzureCredential tijdens runtime in elke app die op die computer wordt uitgevoerd.

Debuggen van een referentie

Als u een onverwacht probleem wilt vaststellen of wilt weten wat een referentie doet, schakelt u logboekregistratie in uw app in. Voorbeeld:

import { setLogLevel, AzureLogger } from "@azure/logger";
import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

// Constant for the Azure Identity log prefix
const AZURE_IDENTITY_LOG_PREFIX = "azure:identity";

// override logging to output to console.log (default location is stderr)
// only log messages that start with the Azure Identity log prefix
setLogLevel("verbose");
AzureLogger.log = (...args) => {
  const message = args[0];
  if (typeof message === 'string' && message.startsWith(AZURE_IDENTITY_LOG_PREFIX)) {
    console.log(...args);
  }
};

// Get storage account name from environment variable
const storageAccountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;

if (!storageAccountName) {
    throw new Error("AZURE_STORAGE_ACCOUNT_NAME environment variable is required");
}

const credential = new DefaultAzureCredential({ 
    requiredEnvVars: [ "AZURE_TOKEN_CREDENTIALS" ]
});


const blobServiceClient = new BlobServiceClient(
    `https://${storageAccountName}.blob.core.windows.net`,
    credential
);

azure:identity:info EnvironmentCredential => Found the following environment variables: 
azure:identity:verbose EnvironmentCredential => AZURE_CLIENT_SEND_CERTIFICATE_CHAIN: undefined; sendCertificateChain: false
azure:identity:info WorkloadIdentityCredential => Found the following environment variables:
azure:identity:warning DefaultAzureCredential => Skipped createDefaultWorkloadIdentityCredential because of an error creating the credential: CredentialUnavailableError: WorkloadIdentityCredential: is unavailable. clientId is a required parameter. In DefaultAzureCredential and ManagedIdentityCredential, this can be provided as an environment variable - "AZURE_CLIENT_ID".
        See the troubleshooting guide for more information: https://aka.ms/azsdk/js/identity/workloadidentitycredential/troubleshoot
azure:identity:info ManagedIdentityCredential => Using DefaultToImds managed identity.
azure:identity:warning DefaultAzureCredential => Skipped createDefaultBrokerCredential because of an error creating the credential: Error: Broker for WAM was requested, but no plugin was configured or no authentication record was found. You must install the @azure/identity-broker plugin package (npm install --save @azure/identity-broker) and enable it by importing `useIdentityPlugin` from `@azure/identity` and calling useIdentityPlugin(nativeBrokerPlugin) before using enableBroker.
azure:identity:info DefaultAzureCredential => getToken() => Skipping createDefaultWorkloadIdentityCredential, reason: WorkloadIdentityCredential: is unavailable. clientId is a required parameter. In DefaultAzureCredential and ManagedIdentityCredential, this can be provided as an environment variable - "AZURE_CLIENT_ID".
        See the troubleshooting guide for more information: https://aka.ms/azsdk/js/identity/workloadidentitycredential/troubleshoot
azure:identity:info ManagedIdentityCredential => getToken() => Using the MSAL provider for Managed Identity.
azure:identity:info ManagedIdentityCredential - Token Exchange => ManagedIdentityCredential - Token Exchange: Unavailable. The environment variables needed are: AZURE_CLIENT_ID (or the client ID sent through the parameters), AZURE_TENANT_ID and AZURE_FEDERATED_TOKEN_FILE
azure:identity:info ManagedIdentityCredential => getToken() => MSAL Identity source: DefaultToImds
azure:identity:info ManagedIdentityCredential => getToken() => Using the IMDS endpoint to probe for availability.
azure:identity:info ManagedIdentityCredential - IMDS => ManagedIdentityCredential - IMDS: Pinging the Azure IMDS endpoint
azure:identity:verbose ManagedIdentityCredential - IMDS => ManagedIdentityCredential - IMDS: Caught error RestError: connect ENETUNREACH 169.254.169.254:80
azure:identity:info ManagedIdentityCredential - IMDS => ManagedIdentityCredential - IMDS: The Azure IMDS endpoint is unavailable
azure:identity:error ManagedIdentityCredential => getToken() => ERROR. Scopes: https://storage.azure.com/.default. Error message: Attempted to use the IMDS endpoint, but it is not available..
azure:identity:info AzureCliCredential => getToken() => Using the scope https://storage.azure.com/.default
azure:identity:info AzureCliCredential => getToken() => expires_on is available and is valid, using it
azure:identity:info AzureCliCredential => getToken() => SUCCESS. Scopes: https://storage.azure.com/.default.

In de voorgaande uitvoer ziet u dat DefaultAzureCredential een token is verkregen met behulp van AzureCliCredential.