Klientská knihovna Azure Identity pro JavaScript – verze 4.4.0

Knihovna identit Azure poskytuje ověřování tokenu Microsoft Entra ID (dříve Azure Active Directory) prostřednictvím sady pohodlných implementací tokenů TokenCreden tial.

Příklady různých přihlašovacích údajů najdete na stránce příklady identit Azure.

Klíčové odkazy:

• zdrojového kódu
• balíčku (npm)
• Referenční dokumentace k rozhraní API
• Dokumentace k Microsoft Entra ID
• ukázky

Začínáme

Aktuálně podporovaná prostředí

• LTS verze Node.js
  • Poznámka: Pokud vaše aplikace běží na Node.js v8 nebo nižší a nemůžete upgradovat verzi Node.js na nejnovější stabilní verzi, připněte závislost @azure/identity na verzi 1.1.0.
• Nejnovější verze Safari, Chrome, Edge a Firefox.
  • Poznámka: Mezi různými přihlašovacími údaji exportovanými v této knihovně je InteractiveBrowserCredential jediný, který je podporovaný v prohlížeči.

Další podrobnosti najdete v našich zásadách podpory .

Instalace balíčku

Instalace identity Azure s využitím npm:

npm install --save @azure/identity

Požadavky

• Předplatné Azure.
• Volitelné: Azure CLI a/nebo Azure PowerShellu může být také užitečné pro ověřování ve vývojovém prostředí a správě rolí účtu.

Kdy použít @azure/identity

Třídy přihlašovacích údajů vystavené @azure/identity se zaměřují na to, aby poskytovaly nejjednodušší způsob, jak ověřovat klienty Sady Azure SDK místně, ve vývojových prostředích a v produkčním prostředí. Snažíme se pro jednoduchost a rozumnou podporu ověřovacích protokolů pokrýt většinu scénářů ověřování, které jsou v Azure možné. Aktivně rozšiřujeme o další scénáře. Úplný seznam nabízených přihlašovacích údajů najdete v části třídy přihlašovacích údajů.

Všechny typy přihlašovacích údajů poskytované @azure/identity jsou podporovány v Node.js. V prohlížečích InteractiveBrowserCredential je typ přihlašovacích údajů, který se má použít pro scénáře základního ověřování.

Většina typů přihlašovacích údajů nabízených používáknihovnu Microsoft Authentication Library pro JavaScript (MSAL.js). Konkrétně používáme knihovny MSAL.js v2, které používají tok autorizačního kódu OAuth 2.0 s PKCE a jsou kompatibilní s OpenID. I když se @azure/identity zaměřuje na jednoduchost, jsou knihovny MSAL.js, jako jsou @azure/msal-common, @azure/msal-nodea @azure/msal-browser, navrženy tak, aby poskytovaly robustní podporu ověřovacích protokolů, které Azure podporuje.

Kdy použít něco jiného

Typy přihlašovacích údajů @azure/identity jsou implementace @azure/core-authtřídy TokenCredential. V zásadě každý objekt s getToken metodou, která splňuje getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null> bude fungovat jako TokenCredential. To znamená, že vývojáři mohou napsat své vlastní typy přihlašovacích údajů, které podporují případy ověřování, které @azure/identity. Další informace najdete v tématu vlastní přihlašovací údaje.

I když naše typy přihlašovacích údajů podporují mnoho pokročilých případů, můžou vývojáři chtít mít plnou kontrolu nad ověřovacím protokolem. Pro tento případ použití doporučujeme použít přímo knihovnu Microsoft Authentication Library pro JavaScript (MSAL.js). Další informace najdete na následujících odkazech:

• Některé pokročilé případy použití vystihovíme na stránce příklady identit Azure.
  • Tam máme konkrétně část Pokročilé příklady.
  • Máme také část, která ukazuje, jak ověřování pomocí KNIHOVNY MSAL přímo.

V případě pokročilých pracovních postupů ověřování v prohlížeči máme oddíl, ve kterém předvádíme, jak používat knihovnu @azure/msal-browser přímo k ověřování klientů sady Azure SDK.

Ověření klienta ve vývojovém prostředí

I když ve vaší aplikaci hostované v Azure doporučujeme používat spravovanou identitu, je typické, že vývojář použije vlastní účet pro ověřování volání služeb Azure při místním ladění a spouštění kódu. K provedení tohoto ověřování ve vývojovém prostředí můžete použít několik vývojářských nástrojů.

Ověřování pomocí Azure Developer CLI

Vývojáři kódující mimo integrované vývojové prostředí můžou k ověření použít také Azure Developer CLI. Aplikace používající DefaultAzureCredential nebo AzureDeveloperCliCredential pak můžou tento účet použít k ověřování volání v aplikaci při místním spuštění.

Pokud se chcete ověřit pomocí Azure Developer CLI, můžou uživatelé spustit příkaz azd auth login. Pro uživatele spuštěné v systému s výchozím webovým prohlížečem spustí Azure Developer CLI prohlížeč pro ověření uživatele.

Pro systémy bez výchozího webového prohlížeče použije příkaz azd auth login --use-device-code tok ověřování kódu zařízení.

Ověřování prostřednictvím Azure CLI

Aplikace využívající AzureCliCredential, ať už přímo nebo prostřednictvím DefaultAzureCredential, můžou k ověřování volání v aplikaci při místním spuštění použít účet Azure CLI.

Ověření pomocí Azure CLI uživatelé můžou spustit příkaz az login. Pro uživatele spuštěné v systému s výchozím webovým prohlížečem azure cli spustí prohlížeč pro ověření uživatele.

Pro systémy bez výchozího webového prohlížeče použije příkaz az login tok ověřování kódu zařízení. Uživatel může také vynutit, aby azure CLI používalo tok kódu zařízení místo spuštění prohlížeče zadáním argumentu --use-device-code.

Ověřování pomocí Azure PowerShellu

Aplikace používající AzurePowerShellCredential, ať už přímo nebo prostřednictvím DefaultAzureCredential, můžou k ověřování volání v aplikaci při místním spuštění použít účet připojený k Azure PowerShellu.

Pokud se chcete ověřit pomocí Azure PowerShellu, uživatelé můžou spustit rutinu Connect-AzAccount. Ve výchozím nastavení, jako je Azure CLI, Connect-AzAccount spustí výchozí webový prohlížeč pro ověření uživatelského účtu.

Pokud v relaci nejde podporovat interaktivní ověřování, bude argument -UseDeviceAuthentication vynutit, aby místo toho použila ověřovací tok kódu zařízení, podobně jako odpovídající možnost v přihlašovacích údajích Azure CLI.

Ověřování pomocí editoru Visual Studio Code

Vývojáři, kteří používají Visual Studio Code, můžou k ověřování prostřednictvím editoru použít rozšíření účtu Azure. Aplikace používající VisualStudioCodeCredential pak můžou tento účet použít k ověřování volání v aplikaci při místním spuštění.

Pokud se chcete ověřit v editoru Visual Studio Code, ujistěte se, že je nainstalované rozšíření účtu Azure. Po instalaci otevřete paletu příkazů a spusťte příkaz Azure: Přihlásit se.

Kromě toho použijte balíček modulu plug-in @azure/identity-vscode. Tento balíček poskytuje závislosti VisualStudioCodeCredential a umožňuje ho. Viz pluginy.

Jedná se o známý problém, že VisualStudioCodeCredential nefunguje s rozšířením účtu Azure novějšími verzemi než 0.9.11. Probíhá dlouhodobé řešení tohoto problému. Do té doby zvažte ověřování prostřednictvím azure CLI.

Ověření klienta v prohlížečích

Abychom mohli ověřovat klienty Azure SDK ve webových prohlížečích, nabízíme InteractiveBrowserCredential, které je možné nastavit tak, aby používaly přesměrování nebo automaticky otevírané okno k dokončení ověřovacího toku. Nejprve je potřeba vytvořit registrace aplikace Azure na webu Azure Portal pro vaši webovou aplikaci.

Klíčové koncepty

Pokud používáte @azure/identity nebo Microsoft Entra ID poprvé, přečtěte si nejprve Použití @azure/identity s Microsoft Entra ID. Tento dokument poskytuje hlubší přehled o platformě a o tom, jak správně nakonfigurovat účet Azure.

Pověření

Přihlašovací údaje jsou třída, která obsahuje nebo může získat data potřebná pro klienta služby k ověření požadavků. Klienti služeb napříč sadou Azure SDK přijímají přihlašovací údaje při jejich vytváření. Klienti služeb používají tyto přihlašovací údaje k ověřování požadavků na službu.

Knihovna Identit Azure se zaměřuje na ověřování OAuth pomocí Microsoft Entra ID a nabízí celou řadu tříd přihlašovacích údajů, které umožňují získat token Microsoft Entra pro ověřování žádostí o služby. Všechny třídy přihlašovacích údajů v této knihovně jsou implementace TokenCredential abstraktní třídy a všechny z nich lze použít k vytvoření klientů služby schopných ověřování pomocí TokenCredential.

Viz třídy přihlašovacích údajů.

DefaultAzureCredential

DefaultAzureCredential je vhodné pro většinu scénářů, ve kterých má být aplikace nakonec spuštěna v Azure. Důvodem je to, že DefaultAzureCredential kombinuje přihlašovací údaje, které se běžně používají k ověření při nasazení s přihlašovacími údaji použitými k ověření ve vývojovém prostředí.

Poznámka: DefaultAzureCredential je určená ke zjednodušení práce se sadou SDK tím, že zpracovává běžné scénáře s rozumným výchozím chováním. Vývojáři, kteří chtějí mít větší kontrolu nebo jejichž scénář není ve výchozím nastavení obsluhován, by měli používat jiné typy přihlašovacích údajů.

Pokud se používá z Node.js, DefaultAzureCredential se pokusí ověřit pomocí následujících mechanismů v pořadí:

1. prostředí – DefaultAzureCredential přečte informace o účtu zadané prostřednictvím proměnných prostředí a použije ho k ověření.
2. identity úloh – Pokud je aplikace nasazená do služby Azure Kubernetes Service s povolenou spravovanou identitou, DefaultAzureCredential se s ní ověří.
3. spravované identity – pokud je aplikace nasazená na hostitele Azure s povolenou spravovanou identitou, DefaultAzureCredential se u daného účtu ověří.
4. Azure CLI – pokud vývojář ověřil účet prostřednictvím příkazu az login Azure CLI, DefaultAzureCredential se u daného účtu ověří.
5. Azure PowerShellu – Pokud se vývojář ověřil pomocí modulu Azure PowerShellu Connect-AzAccount příkazu, DefaultAzureCredential se u daného účtu ověří.
6. azure Developer CLI – pokud vývojář ověřil účet prostřednictvím azd auth login azure Developer CLI, DefaultAzureCredential se u daného účtu ověří.

Zásady pokračování

Od verze 3.3.0 se DefaultAzureCredential pokusí ověřit pomocí všech přihlašovacích údajů vývojáře, dokud nebude úspěšný, bez ohledu na chyby, ke kterým došlo u předchozích přihlašovacích údajů vývojáře. Vývojářské přihlašovací údaje se například mohou pokusit získat token a selhat, takže DefaultAzureCredential bude pokračovat k dalším přihlašovacím údajům v toku. Přihlašovací údaje nasazené služby zastaví tok s vyvolánou výjimkou, pokud se můžou pokusit o načtení tokenu, ale neobdrží ho.

To umožňuje vyzkoušet všechny přihlašovací údaje vývojáře na vašem počítači a mít předvídatelné nasazené chování.

Poznámka o VisualStudioCodeCredential

Kvůli známému problémuse VisualStudioCodeCredential odebral z řetězu tokenů DefaultAzureCredential. Po vyřešení problému v budoucí verzi se tato změna vrátí.

Moduly plug-in

Azure Identity for JavaScript poskytuje rozhraní API modulu plug-in, které nám umožňuje poskytovat určité funkce prostřednictvím samostatných balíčků modulů plug-in . Balíček @azure/identity exportuje funkci nejvyšší úrovně (useIdentityPlugin), kterou lze použít k povolení modulu plug-in. Nabízíme dva balíčky modulů plug-in:

• @azure/identity-broker, který poskytuje podporu zprostředkovaného ověřování prostřednictvím nativního zprostředkovatele, jako je například Správce webových účtů.
• @azure/identity-cache-persistence, která poskytuje trvalé ukládání tokenů do mezipaměti v Node.js pomocí nativního zabezpečeného úložného systému poskytovaného vaším operačním systémem. Tento modul plug-in umožňuje uchovávat hodnoty access_token uložených v mezipaměti napříč relacemi, což znamená, že interaktivní tok přihlášení se nemusí opakovat, dokud je token uložený v mezipaměti k dispozici.

Příklady

Další příklady použití různých přihlašovacích údajů najdete na stránce Příklady identit Azure

Ověřování pomocí DefaultAzureCredential

Tento příklad ukazuje ověřování KeyClient z @azure/keyvault-keys klientské knihovny pomocí 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);

Určení spravované identity přiřazené uživatelem pomocí DefaultAzureCredential

Relativně běžný scénář zahrnuje ověřování pomocí spravované identity přiřazené uživatelem pro prostředek Azure. Prozkoumejte příklad ověřování spravované identity přiřazené uživatelem pomocí defaultAzureCredential a podívejte se, jak se jedná o relativně jednoduchou úlohu, která se dá nakonfigurovat pomocí proměnných prostředí nebo kódu.

Definování vlastního toku ověřování pomocí ChainedTokenCredential

I když je DefaultAzureCredential obecně nejrychlejší způsob, jak začít s vývojem aplikací pro Azure, pokročilejší uživatelé můžou chtít přihlašovací údaje při ověřování přizpůsobit. ChainedTokenCredential umožňuje uživatelům kombinovat více instancí přihlašovacích údajů, aby definovali přizpůsobený řetěz přihlašovacích údajů. Tento příklad ukazuje vytvoření ChainedTokenCredential, který se pokusí ověřit pomocí dvou různých nakonfigurovaných instancí ClientSecretCredential, k ověření KeyClient z @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);

Podpora spravované identity

Ověřování spravované identity se podporuje prostřednictvím nebo tříd přihlašovacích údajů přímo pro následující služby Azure:

• Azure App Service a Azure Functions
• azure Arc
• azure Cloud Shell
• azure Kubernetes Service
• Azure Service Fabric
• virtuálních počítačů Azure
• škálovací sady virtuálních počítačů Azure

Příklady použití spravované identity pro ověřování najdete v tématu příklady.

Konfigurace cloudu

Přihlašovací údaje se ve výchozím nastavení ověřují do koncového bodu Microsoft Entra pro veřejný cloud Azure. Pokud chcete získat přístup k prostředkům v jiných cloudech, jako je Azure Government nebo privátní cloud, nakonfigurujte přihlašovací údaje pomocí argumentu authorityHost v konstruktoru. Rozhraní AzureAuthorityHosts definuje autority pro dobře známé cloudy. Pro cloud státní správy USA můžete vytvořit instanci přihlašovacích údajů tímto způsobem:

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

Tato konfigurace nevyžaduje všechny přihlašovací údaje. Přihlašovací údaje, které se ověřují prostřednictvím vývojového nástroje, jako je AzureCliCredential, používají konfiguraci tohoto nástroje. Podobně VisualStudioCodeCredential přijímá argument authorityHost, ale ve výchozím nastavení se nastaví authorityHost odpovídající Azure: Cloud editoru Visual Studio Code.

Třídy přihlašovacích údajů

Ověřování aplikací hostovaných v Azure

Pověření	Zvyk	Příklad
DefaultAzureCredential	Poskytuje zjednodušené prostředí pro ověřování, které umožňuje rychle začít s vývojem aplikací spuštěných v Azure.	příklad
ChainedTokenCredential	Umožňuje uživatelům definovat vlastní toky ověřování, které vytváří více přihlašovacích údajů.	příklad
EnvironmentCredential	Ověřuje instanční objekt nebo uživatele prostřednictvím informací o přihlašovacích údajích zadaných v proměnných prostředí.	příklad
ManagedIdentityCredential	Ověřuje spravovanou identitu prostředku Azure.	příklad
WorkloadIdentityCredential	Podporuje ID úlohy Microsoft Entra v Kubernetes.	příklad

Ověřování instančních objektů

Pověření	Zvyk	Příklad	Odkaz
AzurePipelinesCredential	Podporuje ID úlohy Microsoft Entra ve službě Azure Pipelines.	příklad
ClientAssertionCredential	Ověřuje instanční objekt pomocí podepsaného klientského kontrolního výrazu.	příklad	ověřování instančního objektu
ClientCertificateCredential	Ověřuje instanční objekt pomocí certifikátu.	příklad	ověřování instančního objektu
ClientSecretCredential	Ověřuje instanční objekt pomocí tajného kódu.	příklad	ověřování instančního objektu

Ověřování uživatelů

Pověření	Zvyk	Příklad	Odkaz
AuthorizationCodeCredential	Ověřuje uživatele pomocí dříve získaného autorizačního kódu.	příklad	ověřovací kód OAuth2
DeviceCodeCredential	Interaktivně ověřuje uživatele na zařízeních s omezeným uživatelským rozhraním.	příklad	ověřování kódu zařízení
InteractiveBrowserCredential	Interaktivně ověřuje uživatele pomocí výchozího systémového prohlížeče. Přečtěte si další informace o tom, jak k tomu dochází zde.	příklad	ověřovací kód OAuth2
OnBehalfOfCredential	Rozšíří delegovanou identitu uživatele a oprávnění prostřednictvím řetězu žádostí.		ověřování jménem
UsernamePasswordCredential	Ověřuje uživatele pomocí uživatelského jména a hesla.	příklad	uživatelské jméno a ověřování heslem

Ověřování prostřednictvím vývojových nástrojů

Pověření	Zvyk	Příklad	Odkaz
AzureCliCredential	Ověřování ve vývojovém prostředí pomocí Azure CLI	příklad	ověřování Azure CLI
AzureDeveloperCliCredential	Ověřte se ve vývojovém prostředí pomocí povoleného uživatele nebo instančního objektu v Azure Developer CLI.		Referenční rozhraní příkazového řádku azure pro vývojáře
AzurePowerShellCredential	Ověřování ve vývojovém prostředí pomocí Azure PowerShellu	příklad	ověřování Azure PowerShellu
VisualStudioCodeCredential	Ověřuje se jako uživatel přihlášený k rozšíření účtu Azure v editoru Visual Studio Code.		rozšíření účtu Azure VS Code

Proměnné prostředí

DefaultAzureCredential a EnvironmentCredential je možné nakonfigurovat s proměnnými prostředí. Každý typ ověřování vyžaduje hodnoty pro konkrétní proměnné.

Instanční objekt s tajným kódem

Název proměnné	Hodnota
AZURE_CLIENT_ID	ID aplikace Microsoft Entra
AZURE_TENANT_ID	ID tenanta Microsoft Entra aplikace
AZURE_CLIENT_SECRET	jeden z tajných kódů klienta aplikace

Instanční objekt s certifikátem

Název proměnné	Hodnota
AZURE_CLIENT_ID	ID aplikace Microsoft Entra
AZURE_TENANT_ID	ID tenanta Microsoft Entra aplikace
AZURE_CLIENT_CERTIFICATE_PATH	cesta k souboru certifikátu s kódováním PEM včetně privátního klíče
AZURE_CLIENT_CERTIFICATE_PASSWORD	heslo k souboru certifikátu, pokud existuje

Uživatelské jméno a heslo

Název proměnné	Hodnota
AZURE_CLIENT_ID	ID aplikace Microsoft Entra
AZURE_TENANT_ID	ID tenanta Microsoft Entra aplikace
AZURE_USERNAME	uživatelské jméno (obvykle e-mailová adresa)
AZURE_PASSWORD	heslo daného uživatele

Konfigurace se pokouší ve výše uvedeném pořadí. Pokud jsou například k dispozici hodnoty pro tajný klíč klienta a certifikát, použije se tajný klíč klienta.

Průběžné vyhodnocování přístupu

Od verze 3.3.0 je možné přistupovat k prostředkům chráněným průběžného vyhodnocování přístupu (CAE) na základě jednotlivých požadavků. To je možné povolit pomocírozhraní API . CaE se nepodporuje pro přihlašovací údaje vývojáře.

Ukládání tokenů do mezipaměti

Ukládání tokenů do mezipaměti je funkce, kterou poskytuje knihovna identit Azure, která umožňuje aplikacím:

• Tokeny mezipaměti v paměti (výchozí) a na disku (výslovný souhlas)
• Zvýšení odolnosti a výkonu
• Snižte počet žádostí provedených na ID Microsoft Entra, abyste získali přístupové tokeny.

Knihovna Identit Azure nabízí ukládání do mezipaměti i trvalé ukládání do mezipaměti na disku. Další podrobnosti najdete v dokumentaci k ukládání tokenů do mezipaměti .

Zprostředkované ověřování

Zprostředkovatel ověřování je aplikace, která běží na počítači uživatele a spravuje ověřování handshakes a údržbu tokenů pro připojené účty. V současné době se podporuje pouze Správce webových účtů systému Windows (WAM). Pokud chcete povolit podporu, použijte balíček @azure/identity-broker. Podrobnosti o ověřování pomocí WAM najdete v dokumentaci k modulu plug-in broker.

Řešení problémů

Pomoc s řešením potíží najdete v průvodci odstraňováním potíží .

Další kroky

Přečtěte si dokumentaci.

Dokumentaci k rozhraní API pro tuto knihovnu najdete na našem webu dokumentace .

Podpora klientské knihovny

Klientské knihovny a knihovny pro správu uvedené na stránce vydaných verzí sady Azure SDK, které podporují ověřování Microsoft Entra, přijímají přihlašovací údaje z této knihovny. Další informace o používání těchto knihoven najdete v dokumentaci, která je propojená ze stránky vydaných verzí.

Známé problémy

Podpora Azure AD B2C

Tato knihovna nepodporuje službu Azure AD B2C.

Další otevřené problémy najdete v úložištiGitHubu knihovny.

Poskytnutí zpětné vazby

Pokud narazíte na chyby nebo máte nějaké návrhy, otevřete problém.

Přispívající

Pokud chcete přispívat do této knihovny, přečtěte si průvodce přispívání a přečtěte si další informace o vytváření a testování kódu.