Delen via


Azure Identity-clientbibliotheek voor JavaScript - versie 4.5.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
  • Nieuwste versies van Safari, Chrome, Edge en Firefox.
    • Opmerking: een van de verschillende referenties die in deze bibliotheek worden geëxporteerd, is InteractiveBrowserCredential de enige die in de browser wordt ondersteund.

Zie ons ondersteuningsbeleidvoor 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> werkt 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 scenario's ondersteunen, willen ontwikkelaars mogelijk Microsoft Authentication Library voor JavaScript (MSAL.js) rechtstreeks gebruiken. Overweeg het gebruik van MSAL.js in de volgende scenario's:

  • Ontwikkelaars die volledige controle willen over het verificatieprotocol en de configuratie ervan.
  • Onze referentietypen zijn ontworpen voor gebruik met Azure SDK-clients met intelligente caching en het vernieuwen van tokens die worden verwerkt in de http-kernlaag. Als u merkt dat u getToken rechtstreeks moet gebruiken, kunt u MSAL.js gebruiken voor meer controle over de verificatiestroom en tokencaching.

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-, voert u de opdracht az loginuit. Voor gebruikers die worden uitgevoerd op een systeem met een standaardwebbrowser, 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-, voert u de Connect-AzAccount-cmdlet uit. Net als de Azure CLI Connect-AzAccount wordt standaard de standaardwebbrowser gestart 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 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 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

DefaultAzureCredential vereenvoudigt verificatie bij het ontwikkelen van apps die in Azure worden geïmplementeerd door referenties te combineren die worden gebruikt in Azure-hostingomgevingen met referenties die worden gebruikt in lokale ontwikkeling. Zie het overzicht defaultAzureCredential voor meer informatie.

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 zijn opgetreden bij eerdere referenties voor ontwikkelaars. Een referentie voor een ontwikkelaar 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 kunnen proberen om tokens op te halen, 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 in 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 DefaultAzureCredential

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

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

// Configure vault URL
const vaultUrl = "https://<your-unique-keyvault-name>.vault.azure.net";
// 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 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 ChainedTokenCredential

Hoewel 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 mogelijk 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 vanuit de @azure/keyvault-keys:

import { ClientSecretCredential, ChainedTokenCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

// Configure variables
const vaultUrl = "https://<your-unique-keyvault-name>.vault.azure.net";
const tenantId = "<tenant-id>";
const clientId = "<client-id>";
const clientSecret = "<client-secret>";
const anotherClientId = "<another-client-id>";
const anotherSecret = "<another-client-secret>";
// 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
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 enum definieert autoriteiten voor bekende clouds. Voor de Cloud van de Amerikaanse overheid kunt u op deze manier een referentie instantiëren:

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

const credential = new ClientSecretCredential(
  "<YOUR_TENANT_ID>",
  "<YOUR_CLIENT_ID>",
  "<YOUR_CLIENT_SECRET>",
  {
    authorityHost: AzureAuthorityHosts.AzureGovernment,
  },
);

Als alternatief voor het opgeven van het argument authorityHost kunt u ook de omgevingsvariabele AZURE_AUTHORITY_HOST instellen op de URL van de instantie van uw cloud. Deze methode is handig bij het configureren van meerdere referenties voor verificatie bij dezelfde cloud of wanneer de geïmplementeerde omgeving de doelcloud moet definiëren:

AZURE_AUTHORITY_HOST=https://login.partner.microsoftonline.cn

De AzureAuthorityHosts enum definieert autoriteiten voor bekende clouds voor uw gemak; Als de instantie voor uw cloud echter niet wordt vermeld in AzureAuthorityHosts, kunt u een geldige instantie-URL doorgeven als een tekenreeksargument. Bijvoorbeeld:

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

const credential = new ClientSecretCredential(
  "<YOUR_TENANT_ID>",
  "<YOUR_CLIENT_ID>",
  "<YOUR_CLIENT_SECRET>",
  {
    authorityHost: "https://login.partner.microsoftonline.cn",
  },
);

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

Referentieketens

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

Door Azure gehoste toepassingen verifiëren

Geloofsbrief Gebruik Voorbeeld
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 (optioneel) wachtwoord van het certificaatbestand, indien van toepassing
AZURE_CLIENT_SEND_CERTIFICATE_CHAIN (optioneel) certificaatketen verzenden in x5c-header ter ondersteuning van onderwerpnaam/verificatie op basis van verleners

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 uitgevoerd in de voorgaande 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 voor het opslaan van 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, een probleemopenen.

Bijdragen

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

indrukken