Delen via


Azure Identity-clientbibliotheek voor JavaScript - versie 4.4.0

De Azure Identity-bibliotheek biedt Microsoft Entra ID (voorheen Azure Active Directory) tokenverificatie via een set handige TokenCredential--implementaties.

Zie de pagina Azure Identity-voorbeeldenpaginavoor voorbeelden van verschillende referenties.

Sleutelkoppelingen:

Slag

Momenteel ondersteunde omgevingen

  • LTS-versies van Node.js
    • Opmerking: Als uw toepassing wordt uitgevoerd op Node.js v8 of lager en u uw Node.js versie niet kunt upgraden naar de meest recente stabiele versie, moet u uw @azure/identity afhankelijkheid vastmaken aan versie 1.1.0.
  • Nieuwste versies van Safari, Chrome, Edge en Firefox.
    • Opmerking: onder de verschillende referenties die in deze bibliotheek worden geëxporteerd, is InteractiveBrowserCredential de enige die wordt ondersteund in de browser.

Zie ons ondersteuningsbeleid voor meer informatie.

Het pakket installeren

Azure Identity installeren met npm:

npm install --save @azure/identity

Voorwaarden

Wanneer gebruikt u @azure/identity

De referentieklassen die door @azure/identity worden weergegeven, zijn gericht op het bieden van de eenvoudigste manier om de Azure SDK-clients lokaal, in uw ontwikkelomgevingen en in productie te verifiëren. We streven naar eenvoud en redelijke ondersteuning van de verificatieprotocollen om de meeste mogelijke verificatiescenario's in Azure te behandelen. We breiden ons uit om meer scenario's te behandelen. Zie de sectie Referentieklassen voor een volledige lijst met de aangeboden referenties.

Alle referentietypen die door @azure/identity worden geleverd, worden ondersteund in Node.js. Voor browsers is InteractiveBrowserCredential het referentietype dat moet worden gebruikt voor basisverificatiescenario's.

De meeste referentietypen die door @azure/identity worden aangeboden, gebruiken de Microsoft Authentication Library voor JavaScript (MSAL.js). We gebruiken met name de v2 MSAL.js-bibliotheken, die gebruikmaken van OAuth 2.0-autorisatiecodestroom met PKCE- en die openID-compatibelezijn. Hoewel @azure/identity zich richt op eenvoud, zijn de MSAL.js bibliotheken, zoals @azure/msal-common, @azure/msal-nodeen @azure/msal-browser, ontworpen om robuuste ondersteuning te bieden voor de verificatieprotocollen die Azure ondersteunt.

Wanneer iets anders te gebruiken

De @azure/identity referentietypen zijn implementaties van @azure/core-verificatieTokenCredential klasse. In principe werkt elk object met een getToken methode die voldoet aan getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null> als een TokenCredential. Dit betekent dat ontwikkelaars hun eigen referentietypen kunnen schrijven om verificatiecases te ondersteunen die niet onder @azure/identityvallen. Zie aangepaste referentiesvoor meer informatie.

Hoewel onze referentietypen veel geavanceerde gevallen ondersteunen, willen ontwikkelaars mogelijk volledige controle over het verificatieprotocol. Voor die use-case raden we u aan om Microsoft Authentication Library voor JavaScript (MSAL.js) rechtstreeks te gebruiken. U kunt meer lezen via de volgende koppelingen:

Voor geavanceerde verificatiewerkstromen in de browser hebben we een sectie waarin we laten zien hoe u de bibliotheek @azure/msal-browser rechtstreeks kunt gebruiken om Azure SDK-clients te verifiëren.

De client verifiëren in de ontwikkelomgeving

Hoewel het raadzaam is om beheerde identiteit te gebruiken in uw door Azure gehoste toepassing, is het gebruikelijk dat een ontwikkelaar zijn eigen account gebruikt voor het verifiëren van aanroepen naar Azure-services wanneer er lokaal code wordt opgespoord en uitgevoerd. Er zijn verschillende ontwikkelhulpprogramma's die kunnen worden gebruikt om deze verificatie uit te voeren in uw ontwikkelomgeving.

Verifiëren via de Azure Developer CLI

Ontwikkelaars die buiten een IDE coderen, kunnen ook de Azure Developer CLI- gebruiken om te verifiëren. Toepassingen die gebruikmaken van de DefaultAzureCredential of de AzureDeveloperCliCredential kunnen dit account vervolgens gebruiken om aanroepen in hun toepassing te verifiëren wanneer ze lokaal worden uitgevoerd.

Om te verifiëren met de Azure Developer CLI-, kunnen gebruikers de opdracht azd auth loginuitvoeren. Voor gebruikers die worden uitgevoerd op een systeem met een standaardwebbrowser, start de Azure Developer CLI de browser om de gebruiker te verifiëren.

Voor systemen zonder een standaardwebbrowser gebruikt de opdracht azd auth login --use-device-code de verificatiestroom voor apparaatcode.

Verifiëren via de Azure CLI

Toepassingen die gebruikmaken van de AzureCliCredential, hetzij rechtstreeks of via de DefaultAzureCredential, kunnen het Azure CLI-account gebruiken om aanroepen in de toepassing te verifiëren wanneer ze lokaal worden uitgevoerd.

Als u wilt verifiëren met de Azure CLI gebruikers de opdracht az loginkunnen uitvoeren. Voor gebruikers die op een systeem met een standaardwebbrowser worden uitgevoerd, start de Azure CLI de browser om de gebruiker te verifiëren.

aanmelden bij Azure CLI-account

Voor systemen zonder een standaardwebbrowser gebruikt de opdracht az login de verificatiestroom voor apparaatcode. De gebruiker kan de Azure CLI ook dwingen om de apparaatcodestroom te gebruiken in plaats van een browser te starten door het argument --use-device-code op te geven.

apparaatcode voor azure CLI-account aanmelden

Verifiëren via Azure PowerShell

Toepassingen die gebruikmaken van de AzurePowerShellCredential, hetzij rechtstreeks of via de DefaultAzureCredential, kunnen het account dat is verbonden met Azure PowerShell gebruiken om aanroepen in de toepassing te verifiëren wanneer ze lokaal worden uitgevoerd.

Als u wilt verifiëren met Azure PowerShell gebruikers de Connect-AzAccount cmdlet kunnen uitvoeren. Net als de Azure CLI start Connect-AzAccount standaard de standaardwebbrowser om een gebruikersaccount te verifiëren.

aanmelden bij een Azure PowerShell-account

Als interactieve verificatie niet kan worden ondersteund in de sessie, dwingt het argument -UseDeviceAuthentication de cmdlet om in plaats daarvan een verificatiestroom voor apparaatcode te gebruiken, vergelijkbaar met de bijbehorende optie in de Azure CLI-referentie.

Verifiëren via Visual Studio Code

Ontwikkelaars die Visual Studio Code gebruiken, kunnen de Azure-accountextensie gebruiken om te verifiëren via de editor. Apps die gebruikmaken van VisualStudioCodeCredential kunnen dit account vervolgens gebruiken om aanroepen in hun app te verifiëren wanneer ze lokaal worden uitgevoerd.

Als u zich wilt verifiëren in Visual Studio Code, moet u ervoor zorgen dat de Azure-accountextensie is geïnstalleerd. Nadat de installatie is uitgevoerd, opent u het opdrachtpalet en voert u de opdracht Azure: Aanmelden uit.

Gebruik daarnaast het @azure/identity-vscode-invoegtoepassingspakket. Dit pakket biedt de afhankelijkheden van VisualStudioCodeCredential en schakelt dit in. Zie Plugins.

Het is een bekend probleem dat VisualStudioCodeCredential niet werkt met Azure-accountextensie nieuwere versies dan 0.9.11. Er wordt een langetermijnoplossing voor dit probleem uitgevoerd. Overweeg ondertussen verificatie via de Azure CLI.

De client verifiëren in browsers

Voor het verifiëren van Azure SDK-clients in webbrowsers bieden we de InteractiveBrowserCredential, die kan worden ingesteld om omleiding of pop-ups te gebruiken om de verificatiestroom te voltooien. U moet eerst een Azure-app-registratie maken in Azure Portal voor uw webtoepassing .

Sleutelbegrippen

Als dit de eerste keer is dat u @azure/identity of Microsoft Entra-id gebruikt, leest u eerst @azure/identity gebruiken met Microsoft Entra ID. Dit document biedt een dieper inzicht in het platform en hoe u uw Azure-account correct configureert.

Geloofsbrief

Een referentie is een klasse die de gegevens bevat die nodig zijn voor een serviceclient om aanvragen te verifiëren. Serviceclients in de Azure SDK accepteren referenties wanneer ze worden samengesteld. Serviceclients gebruiken deze referenties om aanvragen voor de service te verifiëren.

De Azure Identity-bibliotheek is gericht op OAuth-verificatie met Microsoft Entra-id en biedt verschillende referentieklassen die een Microsoft Entra-token kunnen verkrijgen om serviceaanvragen te verifiëren. Alle referentieklassen in deze bibliotheek zijn implementaties van de TokenCredential-klasse abstracte klasse en elk van deze klassen kan worden gebruikt door serviceclients te maken die geschikt zijn voor verificatie met een TokenCredential.

Zie referentieklassen.

DefaultAzureCredential

De DefaultAzureCredential is geschikt voor de meeste scenario's waarin de toepassing uiteindelijk moet worden uitgevoerd in Azure. Dit komt doordat de DefaultAzureCredential referenties combineert die vaak worden gebruikt voor verificatie bij implementatie met referenties die worden gebruikt voor verificatie in een ontwikkelomgeving.

Opmerking: DefaultAzureCredential is bedoeld om aan de slag te gaan met de SDK te vereenvoudigen door algemene scenario's met redelijk standaardgedrag te verwerken. Ontwikkelaars die meer controle willen of waarvan het scenario niet wordt geleverd door de standaardinstellingen, moeten andere referentietypen gebruiken.

Als de DefaultAzureCredential wordt gebruikt vanuit Node.js, probeert de DefaultAzureCredential zich te verifiëren via de volgende mechanismen:

DefaultAzureCredential-verificatiestroom

  1. Environment : de DefaultAzureCredential leest accountgegevens die zijn opgegeven via omgevingsvariabelen en gebruiken om te verifiëren.
  2. Workload Identity: als de toepassing wordt geïmplementeerd in Azure Kubernetes Service waarvoor Managed Identity is ingeschakeld, wordt DefaultAzureCredential ermee geverifieerd.
  3. Managed Identity: als de toepassing is geïmplementeerd op een Azure-host waarvoor Managed Identity is ingeschakeld, wordt de DefaultAzureCredential geverifieerd met dat account.
  4. Azure CLI-: als de ontwikkelaar een account heeft geverifieerd via de azure CLI-opdracht az login, wordt de DefaultAzureCredential met dat account geverifieerd.
  5. Azure PowerShell-: als de ontwikkelaar is geverifieerd met behulp van de Azure PowerShell-module Connect-AzAccount opdracht, wordt de DefaultAzureCredential geverifieerd met dat account.
  6. Azure Developer CLI-: als de ontwikkelaar een account heeft geverifieerd via de azure Developer CLI-opdracht azd auth login, wordt de DefaultAzureCredential geverifieerd met dat account.

Vervolgbeleid

Vanaf versie 3.3.0 probeert DefaultAzureCredential zich te verifiëren met alle referenties van de ontwikkelaar totdat één slaagt, ongeacht eventuele fouten die eerder zijn opgetreden bij de ontwikkelaarsreferenties. Een referentie voor ontwikkelaars kan bijvoorbeeld proberen een token op te halen en te mislukken, zodat DefaultAzureCredential verdergaat met de volgende referentie in de stroom. Geïmplementeerde servicereferenties stoppen de stroom met een gegenereerde uitzondering als ze een token kunnen ophalen, maar deze niet ontvangen.

Hierdoor kunt u alle referenties van de ontwikkelaar op uw computer uitproberen terwijl er voorspelbaar gedrag is geïmplementeerd.

Opmerking over VisualStudioCodeCredential

Vanwege een bekend probleem, is VisualStudioCodeCredential verwijderd uit de DefaultAzureCredential tokenketen. Wanneer het probleem in een toekomstige release wordt opgelost, wordt deze wijziging teruggedraaid.

Invoegtoepassingen

Azure Identity voor JavaScript biedt een api voor invoegtoepassingen waarmee we bepaalde functionaliteit kunnen bieden via afzonderlijke pluginpakketten. Het @azure/identity pakket exporteert een functie op het hoogste niveau (useIdentityPlugin) die kan worden gebruikt om een invoegtoepassing in te schakelen. We bieden twee invoegtoepassingspakketten:

  • @azure/identity-broker, die brokered verificatieondersteuning biedt via een systeemeigen broker, zoals Web Account Manager.
  • @azure/identity-cache-persistence, die permanente tokencaching biedt in Node.js met behulp van een systeemeigen beveiligd opslagsysteem dat door uw besturingssysteem wordt geleverd. Met deze invoegtoepassing kunnen access_token waarden in de cache behouden blijven tussen sessies, wat betekent dat een interactieve aanmeldingsstroom niet hoeft te worden herhaald zolang er een token in de cache beschikbaar is.

Voorbeelden

Meer voorbeelden van het gebruik van verschillende referenties vindt u op pagina azure-identiteitsvoorbeelden

Verifiëren met de DefaultAzureCredential

In dit voorbeeld ziet u hoe u de KeyClient van de @azure/keyvault-keys clientbibliotheek kunt verifiëren met behulp van de DefaultAzureCredential.

// The default credential first checks environment variables for configuration as described above.
// If environment configuration is incomplete, it will try managed identity.

// Azure Key Vault service to use
import { KeyClient } from "@azure/keyvault-keys";

// Azure authentication library to access Azure Key Vault
import { DefaultAzureCredential } from "@azure/identity";

// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();

// Create authenticated client
const client = new KeyClient(vaultUrl, credential);

Een door de gebruiker toegewezen beheerde identiteit opgeven met de DefaultAzureCredential

Een relatief gebruikelijk scenario omvat verificatie met behulp van een door de gebruiker toegewezen beheerde identiteit voor een Azure-resource. Bekijk het voorbeeld van het verifiëren van een door de gebruiker toegewezen beheerde identiteit met DefaultAzureCredential- om te zien hoe dit een relatief eenvoudige taak is die kan worden geconfigureerd met behulp van omgevingsvariabelen of in code.

Een aangepaste verificatiestroom definiëren met de ChainedTokenCredential

Hoewel de DefaultAzureCredential over het algemeen de snelste manier is om aan de slag te gaan met het ontwikkelen van toepassingen voor Azure, willen meer geavanceerde gebruikers de referenties aanpassen die worden overwogen bij het verifiëren. Met de ChainedTokenCredential kunnen gebruikers meerdere referentie-exemplaren combineren om een aangepaste keten met referenties te definiëren. In dit voorbeeld ziet u hoe u een ChainedTokenCredential maakt die probeert te verifiëren met behulp van twee verschillende geconfigureerde exemplaren van ClientSecretCredential, om vervolgens de KeyClient te verifiëren op basis van de @azure/keyvault-keys:

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

// When an access token is requested, the chain will try each
// credential in order, stopping when one provides a token
const firstCredential = new ClientSecretCredential(tenantId, clientId, clientSecret);
const secondCredential = new ClientSecretCredential(tenantId, anotherClientId, anotherSecret);
const credentialChain = new ChainedTokenCredential(firstCredential, secondCredential);

// The chain can be used anywhere a credential is required
import { KeyClient } from "@azure/keyvault-keys";
const client = new KeyClient(vaultUrl, credentialChain);

Ondersteuning voor beheerde identiteit

De beheerde identiteitsverificatie wordt ondersteund via de DefaultAzureCredential of de ManagedIdentityCredential referentieklassen rechtstreeks voor de volgende Azure-services:

Zie de voorbeeldenvoor voorbeelden van het gebruik van beheerde identiteiten voor verificatie.

Cloudconfiguratie

Referenties worden standaard geverifieerd bij het Microsoft Entra-eindpunt voor de openbare Azure-cloud. Als u toegang wilt krijgen tot resources in andere clouds, zoals Azure Government of een privécloud, configureert u referenties met het argument authorityHost in de constructor. De AzureAuthorityHosts-interface definieert autoriteiten voor bekende clouds. Voor de Cloud van de Amerikaanse overheid kunt u op deze manier een referentie instantiëren:

import { AzureAuthorityHosts, ClientSecretCredential } from "@azure/identity";
const credential = new ClientSecretCredential(
  "<YOUR_TENANT_ID>",
  "<YOUR_CLIENT_ID>",
  "<YOUR_CLIENT_SECRET>",
  {
    authorityHost: AzureAuthorityHosts.AzureGovernment,
  }
);

Niet alle referenties vereisen deze configuratie. Referenties die worden geverifieerd via een ontwikkelhulpprogramma, zoals AzureCliCredential, gebruiken de configuratie van dat hulpprogramma. Op dezelfde manier accepteert VisualStudioCodeCredential een authorityHost argument, maar wordt standaard ingesteld op de authorityHost overeenkomende Azure van Visual Studio Code: Cloud-instelling.

Referentieklassen

Door Azure gehoste toepassingen verifiëren

Geloofsbrief Gebruik Voorbeeld
DefaultAzureCredential Biedt een vereenvoudigde verificatie-ervaring om snel toepassingen te ontwikkelen die worden uitgevoerd in Azure. voorbeeld van
ChainedTokenCredential Hiermee kunnen gebruikers aangepaste verificatiestromen definiëren die meerdere referenties opstellen. voorbeeld van
EnvironmentCredential Verifieert een service-principal of gebruiker via referentiegegevens die zijn opgegeven in omgevingsvariabelen. voorbeeld van
ManagedIdentityCredential Verifieert de beheerde identiteit van een Azure-resource. voorbeeld van
WorkloadIdentityCredential Ondersteunt Microsoft Entra Workload ID op Kubernetes. voorbeeld van

Service-principals verifiëren

Geloofsbrief Gebruik Voorbeeld Referentie
AzurePipelinesCredential Ondersteunt Microsoft Entra Workload ID in Azure Pipelines. voorbeeld van
ClientAssertionCredential Verifieert een service-principal met behulp van een ondertekende clientverklaring. voorbeeld van service-principalverificatie
ClientCertificateCredential Verifieert een service-principal met behulp van een certificaat. voorbeeld van service-principalverificatie
ClientSecretCredential Verifieert een service-principal met behulp van een geheim. voorbeeld van service-principalverificatie

Gebruikers verifiëren

Geloofsbrief Gebruik Voorbeeld Referentie
AuthorizationCodeCredential Hiermee verifieert u een gebruiker met een eerder verkregen autorisatiecode. voorbeeld van OAuth2-verificatiecode
DeviceCodeCredential Hiermee wordt een gebruiker interactief geverifieerd op apparaten met een beperkte gebruikersinterface. voorbeeld van verificatie van apparaatcode
InteractiveBrowserCredential Hiermee wordt een gebruiker interactief geverifieerd met de standaardsysteembrowser. Lees meer over hoe dit gebeurt hier. voorbeeld van OAuth2-verificatiecode
OnBehalfOfCredential De gedelegeerde gebruikersidentiteit en -machtigingen doorgeven via de aanvraagketen namens verificatie
UsernamePasswordCredential Hiermee wordt een gebruiker geverifieerd met een gebruikersnaam en wachtwoord. voorbeeld van gebruikersnaam en wachtwoordverificatie

Verifiëren via ontwikkelhulpprogramma's

Geloofsbrief Gebruik Voorbeeld Referentie
AzureCliCredential Verifieer in een ontwikkelomgeving met de Azure CLI. voorbeeld van Azure CLI-verificatie
AzureDeveloperCliCredential Verifieer in een ontwikkelomgeving met de ingeschakelde gebruiker of service-principal in Azure Developer CLI. Azure Developer CLI Reference
AzurePowerShellCredential Verifiëren in een ontwikkelomgeving met behulp van Azure PowerShell. voorbeeld van Azure PowerShell-verificatie
VisualStudioCodeCredential Wordt geverifieerd als de gebruiker die is aangemeld bij de Azure-accountextensie van Visual Studio Code. azure-accountextensie voor VS Code

Omgevingsvariabelen

DefaultAzureCredential en EnvironmentCredential kunnen worden geconfigureerd met omgevingsvariabelen. Voor elk type verificatie zijn waarden vereist voor specifieke variabelen.

Service-principal met geheim

Variabelenaam Waarde
AZURE_CLIENT_ID Id van een Microsoft Entra-toepassing
AZURE_TENANT_ID Id van de Microsoft Entra-tenant van de toepassing
AZURE_CLIENT_SECRET een van de clientgeheimen van de toepassing

Service-principal met certificaat

Variabelenaam Waarde
AZURE_CLIENT_ID Id van een Microsoft Entra-toepassing
AZURE_TENANT_ID Id van de Microsoft Entra-tenant van de toepassing
AZURE_CLIENT_CERTIFICATE_PATH pad naar een MET PEM gecodeerd certificaatbestand met inbegrip van een persoonlijke sleutel
AZURE_CLIENT_CERTIFICATE_PASSWORD wachtwoord van het certificaatbestand, indien van toepassing

Gebruikersnaam en wachtwoord

Variabelenaam Waarde
AZURE_CLIENT_ID Id van een Microsoft Entra-toepassing
AZURE_TENANT_ID Id van de Microsoft Entra-tenant van de toepassing
AZURE_USERNAME een gebruikersnaam (meestal een e-mailadres)
AZURE_PASSWORD het wachtwoord van die gebruiker

De configuratie wordt geprobeerd in de bovenstaande volgorde. Als er bijvoorbeeld waarden voor een clientgeheim en certificaat aanwezig zijn, wordt het clientgeheim gebruikt.

Continue toegangsevaluatie

Vanaf versie 3.3.0 is het openen van resources die worden beveiligd door Continuous Access Evaluation (CAE) per aanvraag mogelijk. Dit kan worden ingeschakeld met behulp van de GetTokenOptions.enableCae(boolean) API-. CAE wordt niet ondersteund voor ontwikkelaarsreferenties.

Tokencaching

Tokencaching is een functie van de Azure Identity-bibliotheek waarmee apps het volgende kunnen doen:

  • Cachetokens in het geheugen (standaard) en op schijf (opt-in).
  • Verbeter de tolerantie en prestaties.
  • Verminder het aantal aanvragen voor Microsoft Entra ID om toegangstokens te verkrijgen.

De Azure Identity-bibliotheek biedt zowel in-memory als permanente schijfcache. Zie de documentatie tokencachingvoor meer informatie.

Brokered-verificatie

Een verificatiebroker is een toepassing die wordt uitgevoerd op de computer van een gebruiker en de verificatiehanddruk en tokenonderhoud voor verbonden accounts beheert. Momenteel wordt alleen de Windows Web Account Manager (WAM) ondersteund. Gebruik het @azure/identity-broker-pakket om ondersteuning in te schakelen. Zie de documentatie van de broker-invoegtoepassingvoor meer informatie over verificatie met behulp van WAM.

Probleemoplossing

Zie de gids voor probleemoplossingvoor hulp bij het oplossen van problemen.

Volgende stappen

De documentatie lezen

API-documentatie voor deze bibliotheek vindt u op onze documentatiesite.

Ondersteuning voor clientbibliotheek

Client- en beheerbibliotheken die worden vermeld op de pagina Azure SDK-releases die ondersteuning bieden voor Microsoft Entra-verificatie accepteren referenties uit deze bibliotheek. Meer informatie over het gebruik van deze bibliotheken in hun documentatie, die is gekoppeld vanaf de releasepagina.

Bekende problemen

Ondersteuning voor Azure AD B2C

Deze bibliotheek biedt geen ondersteuning voor de Azure AD B2C-service.

Zie de GitHub-opslagplaats van de bibliotheekvoor andere openstaande problemen.

Feedback

Als u fouten tegenkomt of suggesties hebt, u een probleemopenen.

Bijdragen

Als u een bijdrage wilt leveren aan deze bibliotheek, leest u de gids voor bijdragen voor meer informatie over het bouwen en testen van de code.

indrukken