Azure Identity-klientbibliotek för JavaScript – version 4.2.1
Azure Identity-biblioteket tillhandahåller Microsoft Entra ID-tokenautentisering (tidigare Azure Active Directory) via en uppsättning praktiska TokenCredential-implementeringar .
Exempel på olika autentiseringsuppgifter finns på sidan med Azure Identity-exempel.
Nyckellänkar:
Komma igång
Migrera från v1 till v2 av @azure/identity
Om du använder v1 av @azure/identity
läser du migreringsguiden för att uppdatera till v2.
Miljöer som stöds för närvarande
-
LTS-versioner av Node.js
-
Observera: Om ditt program körs på Node.js v8 eller lägre och du inte kan uppgradera din Node.js version till den senaste stabila versionen, fäster du beroendet
@azure/identity
på version 1.1.0.
-
Observera: Om ditt program körs på Node.js v8 eller lägre och du inte kan uppgradera din Node.js version till den senaste stabila versionen, fäster du beroendet
- De senaste versionerna av Safari, Chrome, Edge och Firefox.
-
Obs! Bland de olika autentiseringsuppgifter som exporteras i det här biblioteket
InteractiveBrowserCredential
är den enda som stöds i webbläsaren.
-
Obs! Bland de olika autentiseringsuppgifter som exporteras i det här biblioteket
Mer information finns i vår supportpolicy .
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 autentisering i en utvecklingsmiljö och för att 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 dina utvecklingsmiljöer och i produktion. Vi strävar efter enkelhet och rimligt stöd för autentiseringsprotokollen för att täcka de flesta av de 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 den typ av autentiseringsuppgifter som ska användas för grundläggande autentiseringsscenarier InteractiveBrowserCredential
.
De flesta typer av autentiseringsuppgifter som erbjuds via @azure/identity
Microsoft Authentication Library for JavaScript (MSAL.js). Mer specifikt använder vi v2-MSAL.js bibliotek, 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-node och @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
@azure/identity
Autentiseringstyperna är implementeringar av klassen @azure/core-authTokenCredential
. 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 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 fall kanske utvecklare vill ha fullständig kontroll över autentiseringsprotokollet. I det här användningsfallet rekommenderar vi att du använder Microsoft Authentication Library för JavaScript (MSAL.js) direkt. Du kan läsa mer via följande länkar:
- Vi visar några avancerade användningsfall för
@azure/identity
på sidan Azure Identity Examples .- Där har vi specifikt avsnittet Avancerade exempel .
- Vi har också ett avsnitt som visar hur du autentiserar med MSAL direkt.
För avancerade autentiseringsarbetsflöden i webbläsaren har vi ett avsnitt där vi visar hur du använder biblioteket @azure/msal-browser direkt för att autentisera Azure SDK-klienter.
Autentisera klienten i utvecklingsmiljön
Vi rekommenderar att du använder autentisering med hanterad identitet eller tjänstens huvudnamn i produktionsprogrammet, men det är vanligt att en utvecklare använder sitt eget konto för att autentisera anrop till Azure-tjänster vid felsökning och körning av 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][azure_developer_cli] för att autentisera. Program som använder DefaultAzureCredential
eller kan sedan använda det här kontot för att autentisera AzureDeveloperCliCredential
anrop i sina program när de körs lokalt.
Om du vill autentisera med [Azure Developer CLI][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 azd auth login --use-device-code
använder kommandot 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-användare kan du köra kommandot az login
. För användare som kör 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 az login
använder kommandot 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 --use-device-code
ange argumentet .
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-användare kan du köra cmdleten Connect-AzAccount
. Som standard startar ike Azure CLI Connect-AzAccount
standardwebbläsaren för att autentisera ett användarkonto.
Om interaktiv autentisering inte stöds i sessionen -UseDeviceAuthentication
tvingar argumentet cmdleten att använda ett autentiseringsflöde för enhetskod 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 den öppnar du kommandopaletten och kör kommandot Azure: Sign In (Azure: Logga in ).
Använd dessutom plugin-paketet @azure/identity-vscode
. Det här paketet tillhandahåller beroenden för VisualStudioCodeCredential
och aktiverar det. Se Plugin-program.
Det är ett känt problem som VisualStudioCodeCredential
inte fungerar med azure-kontotilläggsversioner 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 InteractiveBrowserCredential
Azure SDK-klienter i webbläsare erbjuder vi , som kan ställas in för att använda omdirigering eller popup-fönster för att slutföra autentiseringsflödet. Du måste först skapa en Azure-appregistrering i Azure-portalen för ditt webbprogram.
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.
Merit
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 en mängd 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 den abstrakta klassen TokenCredential , och vilken som helst av dem kan användas av för att konstruera tjänstklienter som kan autentisera med en TokenCredential.
StandardAzureCredential
DefaultAzureCredential
är lämpligt för de flesta scenarier där programmet är avsett att köras i Azure. Det beror på att kombinerar autentiseringsuppgifter som ofta används för att autentisera när de distribueras med autentiseringsuppgifter som används för att autentisera DefaultAzureCredential
i en utvecklingsmiljö.
DefaultAzureCredential
Obs! Är avsett att förenkla kom igång med SDK genom att hantera vanliga scenarier med rimliga standardbeteenden. Utvecklare som vill ha mer kontroll eller vars scenario inte hanteras av standardinställningarna bör använda andra typer av autentiseringsuppgifter.
Om det används från Node.js försöker autentisera DefaultAzureCredential
via följande mekanismer i ordning:
-
Miljö – läser kontoinformation som
DefaultAzureCredential
anges via miljövariabler och använder den för att autentisera. -
Arbetsbelastningsidentitet – Om programmet distribueras till Azure Kubernetes Service med hanterad identitet aktiverat autentiseras
DefaultAzureCredential
med det. -
Hanterad identitet – Om programmet distribueras till en Azure-värd med Hanterad identitet aktiverat autentiseras
DefaultAzureCredential
med det kontot. -
Azure CLI – Om utvecklaren har autentiserat ett konto via Azure CLI-kommandot
az login
autentiserasDefaultAzureCredential
med det kontot. -
Azure PowerShell – Om utvecklaren har autentiserats med azure PowerShell-modulkommandot autentiseras
Connect-AzAccount
DefaultAzureCredential
med det kontot. -
Azure Developer CLI – Om utvecklaren har autentiserat ett konto via Azure Developer CLI-kommandot
azd auth login
autentiserasDefaultAzureCredential
med det kontot.
Fortsättningsprincip
Från och med version 3.3.0 DefaultAzureCredential
försöker 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 autentiseringsuppgifter för tjänsten stoppar flödet med ett undantag som genereras om de kan försöka hämta token, men inte får något.
På så sätt kan du prova alla autentiseringsuppgifter för utvecklare på datorn samtidigt som du har ett förutsägbart distribuerat beteende.
Obs! VisualStudioCodeCredential
På grund av ett känt problemVisualStudioCodeCredential
har tagits bort från DefaultAzureCredential
tokenkedjan. När problemet har lösts i en framtida version återställs den här ändringen.
Plugin-program
Azure Identity för JavaScript tillhandahåller ett plugin-API som gör att vi kan tillhandahålla vissa funktioner via separata plugin-paket. Paketet @azure/identity
exporterar en toppnivåfunktion (useIdentityPlugin
) som kan användas för att aktivera ett plugin-program. Vi tillhandahåller två plugin-paket:
-
@azure/identity-broker
, som ger stöd för asynkron autentisering via en intern asynkron meddelandekö, till exempel Web Account Manager. -
@azure/identity-cache-persistence
, som tillhandahåller beständig tokencachelagring i Node.js med hjälp av ett internt säkert lagringssystem som tillhandahålls av operativsystemet. Med det här plugin-programmet kan cachelagradeaccess_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 med Azure Identity-exempel
Autentisera med DefaultAzureCredential
Det här exemplet visar hur du autentiserar KeyClient
från klientbiblioteket @azure/keyvault-keys med hjälp av 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);
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 exemplet på Autentisera en användartilldelad hanterad identitet med DefaultAzureCredential för att se hur detta görs till en relativt enkel uppgift som kan konfigureras med hjälp av miljövariabler eller i kod.
Definiera ett anpassat autentiseringsflöde med ChainedTokenCredential
DefaultAzureCredential
Det är vanligtvis det snabbaste sättet att komma igång med att utveckla program för Azure, men mer avancerade användare kanske vill anpassa de autentiseringsuppgifter som beaktas vid autentisering.
ChainedTokenCredential
gör det möjligt för användare att kombinera flera instanser av autentiseringsuppgifter för att definiera en anpassad kedja av 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";
// 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);
Stöd för hanterad identitet
Autentiseringen för hanterad identitet stöds antingen via klasserna DefaultAzureCredential
eller ManagedIdentityCredential
autentiseringsuppgifterna 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 autentiseringsuppgifterna med authorityHost
argumentet i konstruktorn. Gränssnittet AzureAuthorityHosts
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 { AzureAuthorityHosts, ClientSecretCredential } from "@azure/identity";
const credential = new ClientSecretCredential(
"<YOUR_TENANT_ID>",
"<YOUR_CLIENT_ID>",
"<YOUR_CLIENT_SECRET>",
{
authorityHost: AzureAuthorityHosts.AzureGovernment,
}
);
Alla autentiseringsuppgifter kräver inte den här konfigurationen. Autentiseringsuppgifter som autentiseras via ett utvecklingsverktyg, till exempel AzureCliCredential
, använder verktygets konfiguration.
VisualStudioCodeCredential
På samma sätt accepterar ett authorityHost
argument men använder som standard den authorityHost
matchande Inställningen Azure: Cloud i Visual Studio Code.
Autentiseringsklasser
Autentisera Azure-värdbaserade program
Merit | Användning | Exempel |
---|---|---|
DefaultAzureCredential |
Ger en förenklad autentiseringsupplevelse för att snabbt börja utveckla program som körs i Azure. | Exempel |
ChainedTokenCredential |
Gör att användare kan definiera anpassade autentiseringsflöden som består av flera autentiseringsuppgifter. | Exempel |
EnvironmentCredential |
Autentiserar tjänstens huvudnamn eller användare via autentiseringsinformation 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
Merit | Användning | Exempel | Referens |
---|---|---|---|
ClientAssertionCredential |
Autentiserar ett huvudnamn för tjänsten med hjälp av en signerad klientkontroll. | Exempel | Autentisering av tjänstens huvudnamn |
ClientCertificateCredential |
Autentiserar ett huvudnamn för tjänsten med hjälp av ett certifikat. | Exempel | Autentisering av tjänstens huvudnamn |
ClientSecretCredential |
Autentiserar ett huvudnamn för tjänsten med hjälp av en hemlighet. | Exempel | Autentisering av tjänstens huvudnamn |
Autentisera användare
Merit | Användning | Exempel | Referens |
---|---|---|---|
AuthorizationCodeCredential |
Autentiserar en användare med en tidigare hämtad auktoriseringskod. | Exempel | OAuth2-autentiseringskod |
DeviceCodeCredential |
Autentiserar en användare interaktivt på enheter med begränsat användargränssnitt. | Exempel | Autentisering med enhetskod |
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 | Å-vägnar för autentisering | |
UsernamePasswordCredential |
Autentiserar en användare med ett användarnamn och lösenord. | Exempel | Autentisering med användarnamn och lösenord |
Autentisera via utvecklingsverktyg
Merit | Användning | Exempel | Referens |
---|---|---|---|
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 |
Autentiseras när användaren loggas 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 |
lösenord för certifikatfilen, om det finns något |
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 ovanstående ordning. Om det till exempel finns värden för både klienthemligheter och certifikat används klienthemligheten.
Kontinuerlig åtkomstutvärdering
Från och med version 3.3.0 är det möjligt att komma åt resurser som skyddas av kontinuerlig åtkomstutvärdering (CAE) per begäran. Detta kan aktiveras med hjälp av API:etGetTokenOptions.enableCae(boolean)
. 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 asynkron 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). Använd paketet för @azure/identity-broker
att aktivera support. 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.
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 med 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 Azure AD B2C-tjänsten .
Andra öppna problem finns i bibliotekets GitHub-lagringsplats.
Ge feedback
Om du stöter på buggar eller har förslag kan du öppna ett problem.
Bidra
Om du vill bidra till det här biblioteket kan du läsa bidragsguiden om du vill veta mer om hur du skapar och testar koden.
Azure SDK for JavaScript
Feedback
https://aka.ms/ContentUserFeedback.
Kommer snart: Under hela 2024 kommer vi att fasa ut GitHub-problem som feedbackmekanism för innehåll och ersätta det med ett nytt feedbacksystem. Mer information finns i:Skicka och visa feedback för