Azure Identity-klientbibliotek för JavaScript – version 4.5.0

Azure Identity-biblioteket tillhandahåller Microsoft Entra-ID (tidigare Azure Active Directory) tokenautentisering via en uppsättning praktiska TokenCredential- implementeringar.

Exempel på olika autentiseringsuppgifter finns på sidan Azure Identity-exempel.

Nyckellänkar:

• Källkod
• Paket (npm)
• API-referensdokumentation
• Microsoft Entra ID-dokumentation
• Exempel

Komma igång

Miljöer som stöds för närvarande

• LTS-versioner av Node.js
• De senaste versionerna av Safari, Chrome, Edge och Firefox.
  • Obs: Bland de olika autentiseringsuppgifter som exporteras i det här biblioteket är InteractiveBrowserCredential den enda som stöds i webbläsaren.

Mer information finns i vår supportprincip.

Installera paketet

Installera Azure Identity med npm:

npm install --save @azure/identity

Förutsättningar

• En Azure-prenumeration.
• Valfritt: Azure CLI- och/eller Azure PowerShell- kan också vara användbart för att autentisera i en utvecklingsmiljö och hantera kontoroller.

När du ska använda @azure/identity

De autentiseringsklasser som exponeras av @azure/identity fokuserar på att tillhandahålla det enklaste sättet att autentisera Azure SDK-klienter lokalt, i utvecklingsmiljöer och i produktion. Vi strävar efter enkelhet och rimligt stöd för autentiseringsprotokollen för att täcka de flesta autentiseringsscenarier som är möjliga i Azure. Vi expanderar aktivt för att täcka fler scenarier. En fullständig lista över de autentiseringsuppgifter som erbjuds finns i avsnittet autentiseringsklasser.

Alla typer av autentiseringsuppgifter som tillhandahålls av @azure/identity stöds i Node.js. För webbläsare är InteractiveBrowserCredential den typ av autentiseringsuppgifter som ska användas för grundläggande autentiseringsscenarier.

De flesta typer av autentiseringsuppgifter som erbjuds av @azure/identity använder Microsoft Authentication Library för JavaScript (MSAL.js). Mer specifikt använder vi v2 MSAL.js-biblioteken, som använder OAuth 2.0 Authorization Code Flow med PKCE- och är OpenID-kompatibla. Även om @azure/identity fokuserar på enkelhet är de MSAL.js biblioteken, till exempel @azure/msal-common, @azure/msal-nodeoch @azure/msal-browser, utformade för att ge robust stöd för de autentiseringsprotokoll som Azure stöder.

När du ska använda något annat

De @azure/identity typerna av autentiseringsuppgifter är implementeringar av @azure/core-authTokenCredential-klass. I princip fungerar alla objekt med en getToken-metod som uppfyller getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null> som en TokenCredential. Det innebär att utvecklare kan skriva sina egna typer av autentiseringsuppgifter för att stödja autentiseringsfall som inte omfattas av @azure/identity. Mer information finns i anpassade autentiseringsuppgifter.

Även om våra typer av autentiseringsuppgifter stöder många avancerade scenarier kanske utvecklare vill använda Microsoft Authentication Library för JavaScript (MSAL.js) direkt i stället. Överväg att använda MSAL.js i följande scenarier:

• Utvecklare som vill ha fullständig kontroll över autentiseringsprotokollet och dess konfiguration.
• Våra typer av autentiseringsuppgifter är utformade för att användas med Azure SDK-klienter med intelligent cachelagring och tokenuppdatering som hanteras i http-kärnskiktet. Om du behöver använda getToken direkt kan du dra nytta av att använda MSAL.js för mer kontroll över autentiseringsflödet och cachelagring av token.

Du kan läsa mer via följande länkar:

• Vi visar några avancerade användningsfall av @azure/identity på sidan Azure Identity Examples.
  • Där har vi specifikt ett avsnittet Avancerade exempel.
  • Vi har också ett avsnitt som visar hur du Autentisera med MSAL direkt.

För avancerade autentiseringsarbetsflöden i webbläsaren har vi ett avsnitt där vi visar hur du använder @azure/msal-browser-biblioteket direkt för att autentisera Azure SDK-klienter.

Autentisera klienten i utvecklingsmiljön

Vi rekommenderar att du använder hanterad identitet i ditt Azure-värdbaserade program, men det är vanligt att en utvecklare använder sitt eget konto för att autentisera anrop till Azure-tjänster när de felsöker och kör kod lokalt. Det finns flera utvecklarverktyg som kan användas för att utföra den här autentiseringen i utvecklingsmiljön.

Autentisera via Azure Developer CLI

Utvecklare som kodar utanför en IDE kan också använda Azure Developer CLI- för att autentisera. Program som använder DefaultAzureCredential eller AzureDeveloperCliCredential kan sedan använda det här kontot för att autentisera anrop i sitt program när de körs lokalt.

Om du vill autentisera med Azure Developer CLI-kan användarna köra kommandot azd auth login. För användare som körs i ett system med en standardwebbläsare startar Azure Developer CLI webbläsaren för att autentisera användaren.

För system utan en standardwebbläsare använder kommandot azd auth login --use-device-code autentiseringsflödet för enhetskod.

Autentisera via Azure CLI

Program som använder AzureCliCredential, antingen direkt eller via DefaultAzureCredential, kan använda Azure CLI-kontot för att autentisera anrop i programmet när de körs lokalt.

Om du vill autentisera med Azure CLI-kör du kommandot az login. För användare som körs i ett system med en standardwebbläsare startar Azure CLI webbläsaren för att autentisera användaren.

För system utan en standardwebbläsare använder kommandot az login autentiseringsflödet för enhetskod. Användaren kan också tvinga Azure CLI att använda enhetskodflödet i stället för att starta en webbläsare genom att ange argumentet --use-device-code.

Autentisera via Azure PowerShell

Program som använder AzurePowerShellCredential, antingen direkt eller via DefaultAzureCredential, kan använda kontot som är anslutet till Azure PowerShell för att autentisera anrop i programmet när de körs lokalt.

Om du vill autentisera med Azure PowerShell-kör du cmdleten Connect-AzAccount. Precis som i Azure CLI Connect-AzAccount startar standardwebbläsaren som standard för att autentisera ett användarkonto.

Om interaktiv autentisering inte kan stödjas i sessionen tvingar argumentet -UseDeviceAuthentication cmdleten att använda ett flöde för enhetskodautentisering i stället, ungefär som motsvarande alternativ i Azure CLI-autentiseringsuppgiften.

Autentisera via Visual Studio Code

Utvecklare som använder Visual Studio Code kan använda Azure-kontotillägget för att autentisera via redigeraren. Appar som använder VisualStudioCodeCredential kan sedan använda det här kontot för att autentisera anrop i appen när de körs lokalt.

Om du vill autentisera i Visual Studio Code kontrollerar du att Azure-kontotillägget är installerat. När du har installerat öppnar du kommandopaletten och kör kommandot Azure: Sign In.

Använd dessutom @azure/identity-vscode-plugin-paketet. Det här paketet tillhandahåller beroenden för VisualStudioCodeCredential och aktiverar det. Se plugin-program.

Det är ett känt problem att VisualStudioCodeCredential inte fungerar med Azure-kontotillägg versioner som är nyare än 0.9.11. En långsiktig korrigering av det här problemet pågår. Under tiden bör du överväga att autentisera via Azure CLI-.

Autentisera klienten i webbläsare

För att autentisera Azure SDK-klienter i webbläsare erbjuder vi InteractiveBrowserCredential, som kan ställas in för att använda omdirigering eller popup-fönster för att slutföra autentiseringsflödet. Det är nödvändigt att skapa en Azure App Registration- i Azure-portalen för ditt webbprogram först.

Viktiga begrepp

Om det här är första gången du använder @azure/identity eller Microsoft Entra-ID läser du Använda @azure/identity med Microsoft Entra-ID först. Det här dokumentet ger en djupare förståelse för plattformen och hur du konfigurerar ditt Azure-konto korrekt.

Autentiseringsuppgifter

En autentiseringsuppgift är en klass som innehåller eller kan hämta de data som behövs för att en tjänstklient ska kunna autentisera begäranden. Tjänstklienter i Azure SDK accepterar autentiseringsuppgifter när de skapas. Tjänstklienter använder dessa autentiseringsuppgifter för att autentisera begäranden till tjänsten.

Azure Identity-biblioteket fokuserar på OAuth-autentisering med Microsoft Entra-ID och erbjuder olika autentiseringsklasser som kan hämta en Microsoft Entra-token för att autentisera tjänstbegäranden. Alla autentiseringsklasser i det här biblioteket är implementeringar av TokenCredential abstrakt klass, och någon av dem kan användas av för att konstruera tjänstklienter som kan autentisera med en TokenCredential.

Se autentiseringsklasser.

StandardAzureCredential

DefaultAzureCredential förenklar autentiseringen vid utveckling av appar som distribueras till Azure genom att kombinera autentiseringsuppgifter som används i Azure-värdmiljöer med autentiseringsuppgifter som används i lokal utveckling. Mer information finns i Översikt över DefaultAzureCredential.

Fortsättningsprincip

Från och med version 3.3.0 försöker DefaultAzureCredential autentisera med alla autentiseringsuppgifter för utvecklare tills det lyckas, oavsett eventuella fel som tidigare autentiseringsuppgifter för utvecklare har uppstått. En utvecklarautentiseringsuppgift kan till exempel försöka hämta en token och misslyckas, så DefaultAzureCredential fortsätter till nästa autentiseringsuppgift i flödet. Distribuerade tjänstautentiseringsuppgifter stoppar flödet med ett undantag som genereras om de kan försöka hämta token, men inte får något.

Detta gör att du kan prova alla autentiseringsuppgifter för utvecklare på datorn samtidigt som du har förutsägbart distribuerat beteende.

Observera om VisualStudioCodeCredential

På grund av ett känt problemhar VisualStudioCodeCredential tagits bort från DefaultAzureCredential tokenkedjan. När problemet löses i en framtida version återställs den här ändringen.

Plugin-program

Azure Identity for JavaScript tillhandahåller ett plugin-API som gör att vi kan tillhandahålla vissa funktioner via separata plugin-paket. @azure/identity-paketet exporterar en funktion på den översta nivån (useIdentityPlugin) som kan användas för att aktivera ett plugin-program. Vi tillhandahåller två plugin-paket:

• @azure/identity-broker, som tillhandahåller stöd för asynkron autentisering via en intern koordinator, till exempel Web Account Manager.
• @azure/identity-cache-persistence, som tillhandahåller beständig tokencachelagring i Node.js med hjälp av ett inbyggt säkert lagringssystem som tillhandahålls av operativsystemet. Med det här plugin-programmet kan cachelagrade access_token värden bevaras mellan sessioner, vilket innebär att ett interaktivt inloggningsflöde inte behöver upprepas så länge en cachelagrad token är tillgänglig.

Exempel

Du hittar fler exempel på hur du använder olika autentiseringsuppgifter på sidan Azure Identity Examples

Autentisera med DefaultAzureCredential

Det här exemplet visar hur du autentiserar KeyClient från @azure/keyvault-keys-klientbiblioteket med hjälp av 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);

Ange en användartilldelad hanterad identitet med DefaultAzureCredential

Ett relativt vanligt scenario är att autentisera med hjälp av en användartilldelad hanterad identitet för en Azure-resurs. Utforska exempel på autentisera en användartilldelad hanterad identitet med DefaultAzureCredential för att se hur detta görs en relativt enkel uppgift som kan konfigureras med hjälp av miljövariabler eller kod.

Definiera ett anpassat autentiseringsflöde med ChainedTokenCredential

Även om DefaultAzureCredential i allmänhet är det snabbaste sättet att komma igång med att utveckla program för Azure, kan mer avancerade användare vilja anpassa de autentiseringsuppgifter som beaktas vid autentisering. Med ChainedTokenCredential kan användare kombinera flera instanser av autentiseringsuppgifter för att definiera en anpassad kedja med autentiseringsuppgifter. Det här exemplet visar hur du skapar en ChainedTokenCredential som försöker autentisera med hjälp av två olika konfigurerade instanser av ClientSecretCredential, för att sedan autentisera KeyClient från @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);

Stöd för hanterad identitet

hanterad identitetsautentisering stöds antingen via DefaultAzureCredential eller ManagedIdentityCredential autentiseringsklasser direkt för följande Azure-tjänster:

• Azure App Service och Azure Functions
• Azure Arc
• Azure Cloud Shell
• Azure Kubernetes Service
• Azure Service Fabric
• Azure Virtual Machines
• Skalningsuppsättningar för virtuella Azure-datorer

Exempel på hur du använder hanterad identitet för autentisering finns i exemplen.

Molnkonfiguration

Autentiseringsuppgifterna är standard för autentisering till Microsoft Entra-slutpunkten för Azure Public Cloud. Om du vill komma åt resurser i andra moln, till exempel Azure Government eller ett privat moln, konfigurerar du autentiseringsuppgifter med argumentet authorityHost i konstruktorn. AzureAuthorityHosts-uppräkningen definierar myndigheter för välkända moln. För US Government-molnet kan du instansiera en autentiseringsuppgift på det här sättet:

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

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

Som ett alternativ till att ange argumentet authorityHost kan du också ange miljövariabeln AZURE_AUTHORITY_HOST till URL:en för molnmyndigheten. Den här metoden är användbar när du konfigurerar flera autentiseringsuppgifter för att autentisera till samma moln eller när den distribuerade miljön behöver definiera målmolnet:

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

Den AzureAuthorityHosts uppräkning definierar myndigheter för välkända moln för din bekvämlighet; Men om utfärdaren för ditt moln inte finns med i AzureAuthorityHostskan du skicka en giltig utfärdar-URL som ett strängargument. Ett exempel:

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

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

Alla autentiseringsuppgifter kräver inte den här konfigurationen. Autentiseringsuppgifter som autentiserar via ett utvecklingsverktyg, till exempel AzureCliCredential, använder verktygets konfiguration. På samma sätt accepterar VisualStudioCodeCredential ett authorityHost argument, men standardinställningen authorityHost matchande Visual Studio Code-inställningen Azure: Cloud.

Autentiseringsklasser

Autentiseringskedjor

Referens	Användning	Exempel
DefaultAzureCredential	Ger en förenklad autentiseringsupplevelse för att snabbt börja utveckla program som körs i Azure.	exempel
ChainedTokenCredential	Tillåter användare att definiera anpassade autentiseringsflöden som består av flera autentiseringsuppgifter.	exempel

Autentisera Azure-värdbaserade program

Referens	Användning	Exempel
EnvironmentCredential	Autentiserar tjänstens huvudnamn eller användare via information om autentiseringsuppgifter som anges i miljövariabler.	exempel
ManagedIdentityCredential	Autentiserar den hanterade identiteten för en Azure-resurs.	exempel
WorkloadIdentityCredential	Stöder Microsoft Entra-arbetsbelastnings-ID på Kubernetes.	exempel

Autentisera tjänstens huvudnamn

Referens	Användning	Exempel	Hänvisning
AzurePipelinesCredential	Stöder Microsoft Entra-arbetsbelastnings-ID på Azure Pipelines.	exempel
ClientAssertionCredential	Autentiserar ett huvudnamn för tjänsten med hjälp av en signerad klientkontroll.	exempel	Tjänstens huvudnamn autentisering
ClientCertificateCredential	Autentiserar ett huvudnamn för tjänsten med hjälp av ett certifikat.	exempel	Tjänstens huvudnamn autentisering
ClientSecretCredential	Autentiserar ett huvudnamn för tjänsten med hjälp av en hemlighet.	exempel	Tjänstens huvudnamn autentisering

Autentisera användare

Referens	Användning	Exempel	Hänvisning
AuthorizationCodeCredential	Autentiserar en användare med en tidigare erhållen auktoriseringskod.	exempel	OAuth2-autentiseringskod
DeviceCodeCredential	Autentiserar en användare interaktivt på enheter med begränsat användargränssnitt.	exempel	Enhetskodautentisering
InteractiveBrowserCredential	Autentiserar en användare interaktivt med standardsystemwebbläsaren. Läs mer om hur detta händer här.	exempel	OAuth2-autentiseringskod
OnBehalfOfCredential	Sprider den delegerade användaridentiteten och behörigheterna via begärandekedjan		För autentisering
UsernamePasswordCredential	Autentiserar en användare med ett användarnamn och lösenord.	exempel	användarnamn + lösenordsautentisering

Autentisera via utvecklingsverktyg

Referens	Användning	Exempel	Hänvisning
AzureCliCredential	Autentisera i en utvecklingsmiljö med Azure CLI.	exempel	Azure CLI-autentisering
AzureDeveloperCliCredential	Autentisera i en utvecklingsmiljö med den aktiverade användaren eller tjänstens huvudnamn i Azure Developer CLI.		CLI-referens för Azure Developer
AzurePowerShellCredential	Autentisera i en utvecklingsmiljö med Azure PowerShell.	exempel	Azure PowerShell-autentisering
VisualStudioCodeCredential	Autentiserar när användaren loggade in på Azure-kontotillägget för Visual Studio Code.		AZURE-kontotillägg för VS Code

Miljövariabler

DefaultAzureCredential och EnvironmentCredential kan konfigureras med miljövariabler. Varje typ av autentisering kräver värden för specifika variabler.

Tjänstens huvudnamn med hemlighet

Variabelnamn	Värde
AZURE_CLIENT_ID	ID för ett Microsoft Entra-program
AZURE_TENANT_ID	ID för programmets Microsoft Entra-klientorganisation
AZURE_CLIENT_SECRET	en av programmets klienthemligheter

Tjänstens huvudnamn med certifikat

Variabelnamn	Värde
AZURE_CLIENT_ID	ID för ett Microsoft Entra-program
AZURE_TENANT_ID	ID för programmets Microsoft Entra-klientorganisation
AZURE_CLIENT_CERTIFICATE_PATH	sökväg till en PEM-kodad certifikatfil inklusive privat nyckel
AZURE_CLIENT_CERTIFICATE_PASSWORD	(valfritt) lösenord för certifikatfilen, om det finns
AZURE_CLIENT_SEND_CERTIFICATE_CHAIN	(valfritt) skicka certifikatkedjan i x5c-huvudet för att stödja ämnesnamn/utfärdarbaserad autentisering

Användarnamn och lösenord

Variabelnamn	Värde
AZURE_CLIENT_ID	ID för ett Microsoft Entra-program
AZURE_TENANT_ID	ID för programmets Microsoft Entra-klientorganisation
AZURE_USERNAME	ett användarnamn (vanligtvis en e-postadress)
AZURE_PASSWORD	användarens lösenord

Konfigurationen görs i föregående ordning. Om det till exempel finns både värden för en klienthemlighet och ett certifikat används klienthemligheten.

Utvärdering av kontinuerlig åtkomst

Från och med version 3.3.0 är det möjligt att komma åt resurser som skyddas av (CAE) per begäran. Detta kan aktiveras med hjälp av GetTokenOptions.enableCae(boolean) API-. CAE stöds inte för autentiseringsuppgifter för utvecklare.

Cachelagring av token

Cachelagring av token är en funktion som tillhandahålls av Azure Identity-biblioteket som gör att appar kan:

• Cachetoken i minnet (standard) och på disk (anmäl dig).
• Förbättra motståndskraft och prestanda.
• Minska antalet begäranden som görs till Microsoft Entra-ID för att hämta åtkomsttoken.

Azure Identity-biblioteket erbjuder både minnesintern och beständig diskcachelagring. Mer information finns i dokumentationen om cachelagring av token.

Asynkron autentisering

En autentiseringskoordinator är ett program som körs på en användares dator och hanterar handskakningar för autentisering och tokenunderhåll för anslutna konton. För närvarande stöds endast Windows Web Account Manager (WAM). Om du vill aktivera support använder du @azure/identity-broker-paketet. Mer information om hur du autentiserar med WAM finns i dokumentationen för plugin-programmet broker.

Felsökning

Mer information om felsökning finns i felsökningsguiden för .

Nästa steg

Läs dokumentationen

API-dokumentation för det här biblioteket finns på vår -dokumentationswebbplats.

Stöd för klientbibliotek

Klient- och hanteringsbibliotek som visas på sidan Azure SDK-versioner som stöder Microsoft Entra-autentisering accepterar autentiseringsuppgifter från det här biblioteket. Läs mer om hur du använder dessa bibliotek i deras dokumentation, som är länkad från versionssidan.

Kända problem

Stöd för Azure AD B2C

Det här biblioteket stöder inte tjänsten Azure AD B2C.

Andra öppna problem finns i bibliotekets GitHub-lagringsplats.

Ge feedback

Om du stöter på buggar eller har förslag öppna ett problem.

Bidragande

Om du vill bidra till det här biblioteket kan du läsa bidragsguide för att lära dig mer om hur du skapar och testar koden.