Azure Identity-clientbibliotheek voor JavaScript - versie 4.1.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-voorbeelden voor voorbeelden van verschillende referenties.

Belangrijke koppelingen:

Aan de slag

Migreren van v1 naar v2 van @azure/identity

Als u v1 van @azure/identitygebruikt, raadpleegt u de migratiehandleiding voor het bijwerken naar v2.

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 nieuwste stabiele versie, kunt u uw @azure/identity afhankelijkheid vastmaken aan versie 1.1.0.
  • Nieuwste versies van Safari, Chrome, Edge en Firefox.
    • Opmerking: van de verschillende referenties die in deze bibliotheek worden geëxporteerd, InteractiveBrowserCredential is de enige die wordt ondersteund in de browser.

Zie ons ondersteuningsbeleid voor meer informatie.

Het pakket installeren

Installeer Azure Identity met npm:

npm install --save @azure/identity

Vereisten

Wanneer gebruiken @azure/identity

De referentieklassen die door @azure/identity worden weergegeven, zijn gericht op de meest eenvoudige 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 voor de meeste verificatiescenario's die mogelijk zijn in Azure. We breiden actief uit om meer scenario's te behandelen. Zie de sectie Referentieklassen voor een volledige lijst van de aangeboden referenties.

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

De meeste referentietypen die worden aangeboden door @azure/identity de Microsoft Authentication Library voor JavaScript (MSAL.js) gebruiken. We gebruiken met name de v2 MSAL.js bibliotheken, die gebruikmaken van OAuth 2.0 Authorization Code Flow met PKCE en openID-compatibel zijn. Hoewel @azure/identity de nadruk ligt op eenvoud, zijn de MSAL.js bibliotheken, zoals @azure/msal-common, @azure/msal-node en @azure/msal-browser, ontworpen om robuuste ondersteuning te bieden voor de verificatieprotocollen die door Azure worden ondersteund.

Wanneer gebruikt u iets anders?

De @azure/identity referentietypen zijn implementaties van de klasse @azure/core-authTokenCredential. In principe werkt elk object met een getToken methode die voldoet aan getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null> een TokenCredential. Dit betekent dat ontwikkelaars hun eigen referentietypen kunnen schrijven ter ondersteuning van verificatiecases die niet worden gedekt door @azure/identity. Zie Aangepaste referenties voor meer informatie.

Hoewel onze referentietypen veel geavanceerde cases 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 we het gebruik van beheerde identiteit of verificatie van service-principals in uw productietoepassing aanbevelen, is het gebruikelijk dat ontwikkelaars hun eigen account gebruiken voor het verifiëren van aanroepen naar Azure-services bij het opsporen van fouten en het lokaal uitvoeren van code. 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][azure_developer_cli] gebruiken om te verifiëren. Toepassingen die de DefaultAzureCredential of gebruiken 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][azure_developer_cli], kunnen gebruikers de opdracht azd auth loginuitvoeren. Voor gebruikers die op een systeem met een standaardwebbrowser werken, start de Azure Developer CLI de browser om de gebruiker te verifiëren.

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

Verifiëren via de Azure CLI

Toepassingen die gebruikmaken van , AzureCliCredentialrechtstreeks 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 zich wilt verifiëren bij de Azure CLI , kunnen gebruikers de opdracht az loginuitvoeren. Voor gebruikers die op een systeem met een standaardwebbrowser werken, start de Azure Cli de browser om de gebruiker te verifiëren.

Aanmelden bij Azure CLI-account

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

Aanmelden met apparaatcode voor Azure CLI-account

Verifiëren via Azure PowerShell

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

Als u zich wilt verifiëren met Azure PowerShell gebruikers de Connect-AzAccount cmdlet uitvoeren. Standaard start ike de Azure CLI Connect-AzAccount de standaardwebbrowser om een gebruikersaccount te verifiëren.

Aanmelden bij Azure PowerShell-account

Als interactieve verificatie niet kan worden ondersteund in de sessie, dwingt het -UseDeviceAuthentication argument 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 opdrachtenpalet en voert u de opdracht Azure: Aanmelden uit .

Gebruik ook het @azure/identity-vscode invoegtoepassingspakket. Dit pakket biedt de afhankelijkheden van VisualStudioCodeCredential en schakelt deze in. Zie Invoegtoepassingen.

Het is een bekend probleem dat VisualStudioCodeCredential niet werkt met azure-accountextensieversies nieuwer dan 0.9.11. Er wordt gewerkt aan een oplossing voor de lange termijn voor dit probleem. In de tussentijd kunt u overwegen om te verifiëren 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 de Azure Portal voor uw webtoepassing.

Belangrijkste concepten

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

Referentie

Een referentie is een klasse die de gegevens bevat of kan verkrijgen die nodig zijn voor een serviceclient om aanvragen te verifiëren. Serviceclients in de Azure SDK accepteren referenties wanneer ze worden gemaakt. 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 diverse referentieklassen waarmee een Microsoft Entra-token kan worden verkregen om serviceaanvragen te verifiëren. Alle referentieklassen in deze bibliotheek zijn implementaties van de abstracte klasse TokenCredential . Elk van deze klassen kan worden gebruikt om serviceclients te maken die kunnen worden geverifieerd met een TokenCredential.

Zie Referentieklassen.

StandaardAzureCredential

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 wanneer deze worden geïmplementeerd met referenties die worden gebruikt voor verificatie in een ontwikkelomgeving.

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

Als deze wordt gebruikt vanuit Node.js, DefaultAzureCredential wordt geprobeerd om te verifiëren via de volgende mechanismen in volgorde:

DefaultAzureCredential-verificatiestroom

  1. Omgeving : de DefaultAzureCredential leest accountgegevens die zijn opgegeven via omgevingsvariabelen en gebruikt deze om te verifiëren.
  2. Workloadidentiteit: als de toepassing is geïmplementeerd op Azure Kubernetes Service met beheerde identiteit ingeschakeld, DefaultAzureCredential wordt deze geverifieerd.
  3. Beheerde identiteit : als de toepassing wordt geïmplementeerd op een Azure-host waarvoor beheerde identiteit 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 geverifieerd met dat account.
  5. Azure PowerShell: als de ontwikkelaar is geverifieerd met behulp van de opdracht Azure PowerShell moduleConnect-AzAccount, wordt de DefaultAzureCredential geverifieerd met dat account.
  6. Azure Developer CLI: als de ontwikkelaar een account heeft geverifieerd via de opdracht Azure Developer CLIazd auth login, wordt de DefaultAzureCredential geverifieerd met dat account.

Vervolgbeleid

Vanaf versie 3.3.0 DefaultAzureCredential wordt geprobeerd om te verifiëren met alle referenties van de ontwikkelaar totdat één slaagt, ongeacht eventuele fouten die eerdere ontwikkelaarsreferenties hebben ondervonden. Een referentie voor een ontwikkelaar kan bijvoorbeeld proberen een token op te halen en mislukt, dus DefaultAzureCredential gaat door naar de volgende referentie in de stroom. Geïmplementeerde servicereferenties stoppen de stroom met een gegenereerde uitzondering als ze kunnen proberen het token op te halen, maar er geen ontvangen.

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

Opmerking over VisualStudioCodeCredential

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

Invoegtoepassingen

Azure Identity voor JavaScript biedt een API voor invoegtoepassingen waarmee we bepaalde functionaliteit kunnen bieden via afzonderlijke invoegtoepassingspakketten. 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 ondersteuning biedt voor brokered verificatie via een systeemeigen broker, zoals Web Account Manager.
  • @azure/identity-cache-persistence, dat permanente tokencaching biedt in Node.js met behulp van een systeemeigen beveiligd opslagsysteem van uw besturingssysteem. Met deze invoegtoepassing kunnen waarden in de access_token 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 de pagina met azure-identiteitsvoorbeelden

Verifiëren met de DefaultAzureCredential

In dit voorbeeld wordt de KeyClient geverifieerd vanuit de clientbibliotheek @azure/keyvault-keys 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);

Geef een door de gebruiker toegewezen beheerde identiteit op met de DefaultAzureCredential

Een relatief veelvoorkomend scenario omvat verificatie met behulp van een door de gebruiker toegewezen beheerde identiteit voor een Azure-resource. Bekijk het voorbeeld over het verifiëren van een door de gebruiker toegewezen beheerde identiteit met DefaultAzureCredential om te zien hoe dit een relatief eenvoudige taak wordt 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 ervaren gebruikers mogelijk de referenties aanpassen die worden overwogen bij het verifiëren. Met ChainedTokenCredential de kunnen gebruikers meerdere referentie-exemplaren combineren om een aangepaste keten van referenties te definiëren. In dit voorbeeld ziet u hoe u een ChainedTokenCredential maakt die probeert te verifiëren met behulp van twee verschillend geconfigureerde exemplaren van ClientSecretCredential, om vervolgens de KeyClient te verifiëren vanuit 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 identiteiten

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

Zie de voorbeelden voor voorbeelden van het gebruik van beheerde identiteit voor verificatie.

Cloudconfiguratie

Referenties zijn standaard voor verificatie 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 authorityHost argument in de constructor. De AzureAuthorityHosts interface definieert instanties 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,
  }
);

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

Referentieklassen

Door Azure gehoste toepassingen verifiëren

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

Service-principals verifiëren

Referentie Gebruik Voorbeeld Referentie
ClientAssertionCredential Verifieert een service-principal met behulp van een ondertekende clientverklaring. Voorbeeld Verificatie van service-principal
ClientCertificateCredential Verifieert een service-principal met behulp van een certificaat. Voorbeeld Verificatie van service-principal
ClientSecretCredential Verifieert een service-principal met behulp van een geheim. Voorbeeld Verificatie van service-principal

Gebruikers verifiëren

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

Verifiëren via ontwikkelhulpprogramma's

Referentie Gebruik Voorbeeld Referentie
AzureCliCredential Verifiëren in een ontwikkelomgeving met de Azure CLI. Voorbeeld Azure CLI-verificatie
AzureDeveloperCliCredential Verifieer in een ontwikkelomgeving met de ingeschakelde gebruiker of service-principal in Azure Developer CLI. naslaginformatie over Azure Developer CLI
AzurePowerShellCredential Verifieer in een ontwikkelomgeving met behulp van Azure PowerShell. Voorbeeld Azure PowerShell verificatie
VisualStudioCodeCredential Verifieert als de gebruiker die is aangemeld bij de Azure-accountextensie van Visual Studio Code. Vs Code Azure-accountextensie

Omgevingsvariabelen

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

Service-principal met geheim

Naam van de variabele 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

Naam van de variabele 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 certificaatbestand met PEM-codering, inclusief persoonlijke sleutel
AZURE_CLIENT_CERTIFICATE_PASSWORD wachtwoord van het certificaatbestand, indien van toepassing

Gebruikersnaam en wachtwoord

Naam van de variabele 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

Configuratie wordt uitgevoerd in de bovenstaande volgorde. Als bijvoorbeeld waarden voor een clientgeheim en certificaat beide aanwezig zijn, wordt het clientgeheim gebruikt.

Continue toegangsevaluatie

Vanaf versie 3.3.0 is het mogelijk om toegang te krijgen tot resources die worden beveiligd door continue toegangsevaluatie (CAE) op aanvraagbasis. Dit kan worden ingeschakeld met behulp van de GetTokenOptions.enableCae(boolean) API. CAE wordt niet ondersteund voor referenties voor ontwikkelaars.

Token opslaan in cache

Tokencache 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 schijfcaching. Zie de documentatie voor tokencache voor meer informatie.

Brokered-verificatie

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

Problemen oplossen

Zie de handleiding voor probleemoplossing voor hulp bij het oplossen van problemen.

Volgende stappen

Lees de documentatie

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 vindt u in de bijbehorende documentatie, die is gekoppeld vanaf de pagina Releases.

Bekende problemen

Azure AD B2C-ondersteuning

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

Zie de GitHub-opslagplaats van de bibliotheek voor andere openstaande problemen.

Feedback geven

Als u fouten tegenkomt of suggesties hebt, opent u een probleem.

Bijdragen

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

Weergaven