Klientská knihovna Azure Identity pro JavaScript – verze 4.2.1

Knihovna identit Azure poskytuje ověřování tokenem Microsoft Entra ID (dříve Azure Active Directory) prostřednictvím sady praktických implementací TokenCredential .

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

Klíčové odkazy:

• Zdrojový kód
• Balíček (npm)
• Referenční dokumentace k rozhraní API
• Dokumentace k Microsoft Entra ID
• ukázky

Začínáme

Migrace z v1 na v2 z @azure/identity

Pokud používáte verzi v1 systému @azure/identity, projděte si průvodce migrací pro aktualizaci na verzi 2.

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 Node.js verzi na nejnovější stabilní verzi, připněte závislost @azure/identity na verzi 1.1.0.
• Nejnovější verze prohlížečů Safari, Chrome, Edge a Firefox.
  • Poznámka: Mezi různými přihlašovacími údaji exportovanými do této knihovny je jediný, InteractiveBrowserCredential který je v prohlížeči podporovaný.

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

Instalace balíčku

Nainstalujte azure Identity pomocí npmnástroje :

npm install --save @azure/identity

Požadavky

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

Kdy použít atribut @azure/identity

Třídy přihlašovacích údajů, které vystavuje, @azure/identity se zaměřují na poskytování nejjednoduššího způsobu místního ověřování klientů sady Azure SDK, ve vývojových prostředích a v produkčním prostředí. Snažíme se o jednoduchost a přiměřenou podporu ověřovacích protokolů, abychom pokryli většinu scénářů ověřování, které jsou v Azure možné. Aktivně se 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ů .

Node.js podporují všechny typy přihlašovacích údajů, které @azure/identity poskytuje. U prohlížečů se jedná o typ přihlašovacích údajů, InteractiveBrowserCredential který se má použít ve scénářích základního ověřování.

Většina typů přihlašovacích údajů, které @azure/identity nabízí, 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. Knihovny MSAL.js, jako jsou @azure/msal-common, @azure/msal-node a @azure/msal-browser, jsou navrženy @azure/identity tak, aby poskytovaly robustní podporu ověřovacích protokolů, které Azure podporuje.

Kdy použít něco jiného

Typy @azure/identity přihlašovacích údajů jsou implementace třídy @azure/core-authTokenCredential. V zásadě bude každý objekt s metodou getToken , která splňuje požadavky getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null> , fungovat jako TokenCredentialobjekt . To znamená, že vývojáři můžou psát vlastní typy přihlašovacích údajů, které podporují případy ověřování, na které se nevztahuje @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ů, vývojáři můžou 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 si můžete přečíst na následujících odkazech:

• Některé pokročilé případy @azure/identity použití popisujeme na stránce Azure Identity Examples (Příklady identit Azure ).
  • Tam konkrétně máme část Pokročilé příklady .
  • Máme také část, která ukazuje, jak přímo ověřit pomocí KNIHOVNY MSAL.

Pro pokročilé ověřovací pracovní postupy v prohlížeči máme část, kde ukazujeme, jak použít 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ž doporučujeme používat ověřování pomocí spravované identity nebo instančního objektu v produkční aplikaci, je typické, že vývojář při místním ladění a spouštění kódu používá k ověřování volání služeb Azure vlastní účet. 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í Rozhraní příkazového řádku pro vývojáře Azure

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

Pokud se uživatelé chtějí ověřit pomocí [Azure Developer CLI][azure_developer_cli], můžou 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í Rozhraní příkazového řádku Azure Developer CLI prohlížeč, který uživatele ověří.

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

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

Aplikace, které AzureCliCredentialpoužívají , 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žívat účet Azure CLI.

Pokud se uživatelé chtějí ověřit pomocí Azure CLI, 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.

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

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

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

K ověření pomocí Azure PowerShellu můžou uživatelé spustit rutinu Connect-AzAccount . Azure CLI Connect-AzAccount ve výchozím nastavení spustí výchozí webový prohlížeč pro ověření uživatelského účtu.

Pokud se interaktivní ověřování v relaci nepodporuje, -UseDeviceAuthentication argument vynutí, aby rutina místo toho použila tok ověřování kódu zařízení, podobně jako u odpovídající možnosti v přihlašovacích údajích Azure CLI.

Ověřování prostřednictvím editoru Visual Studio Code

Vývojáři používající Visual Studio Code můžou k ověřování prostřednictvím editoru použít rozšíření Azure Account . Aplikace, které používají VisualStudioCodeCredential tento účet, pak můžou tento účet použít k ověřování volání ve své aplikaci, když jsou spuštěné místně.

Pokud chcete provést ověření v editoru Visual Studio Code, ujistěte se, že je nainstalované rozšíření Azure Account. Po instalaci otevřete paletu příkazů a spusťte příkaz Azure: Sign In (Azure: Sign In ).

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

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

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

K ověřování klientů sady Azure SDK ve webových prohlížečích nabízíme InteractiveBrowserCredential, který je možné nastavit tak, aby k dokončení toku ověřování používal přesměrování nebo automaticky otevíraná okna. Nejprve je potřeba vytvořit registraci 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 téma Použití @azure/identity s Microsoft Entra ID . Tento dokument poskytuje hlubší pochopení platformy a toho, jak správně nakonfigurovat účet Azure.

Reference

Přihlašovací údaje jsou třída, která obsahuje nebo může získat data potřebná pro klienta služby k ověřování požadavků. Klienti služby v rámci sady Azure SDK přijímají přihlašovací údaje při jejich vytváření. Klienti služby 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é dají 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 mohou být použity k vytvoření klientů služby schopné ověřování pomocí TokenCredential.

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

Výchozí přihlašovací údajeAzure

Je DefaultAzureCredential vhodný pro většinu scénářů, kdy 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 Má za cíl zjednodušit zahájení práce se sadou SDK tím, že zpracovává běžné scénáře s přiměřeným výchozím chováním. Vývojáři, kteří chtějí mít větší kontrolu nebo jejichž scénář není obsluhován výchozím nastavením, by měli použít jiné typy přihlašovacích údajů.

Pokud se použije z Node.js, DefaultAzureCredential pokusí se provést ověření prostřednictvím následujících mechanismů v tomto pořadí:

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

Zásady pokračování

Od verze 3.3.0 se bude pokoušet o ověření pomocí všech přihlašovacích údajů vývojáře, DefaultAzureCredential dokud nedojde k úspěšnému, bez ohledu na chyby, ke kterým došlo v předchozích přihlašovacích údajích vývojáře. Například přihlašovací údaje vývojáře se můžou pokusit získat token a selžou, takže DefaultAzureCredential budou pokračovat k dalším přihlašovacím údajům v toku. Nasazené přihlašovací údaje služby zastaví tok s vyvolánou výjimkou, pokud se můžou pokusit o načtení tokenu, ale nedostanou ho.

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

Poznámka k tématu VisualStudioCodeCredential

Kvůli známému problémuVisualStudioCodeCredential byl odebrán z řetězu tokenůDefaultAzureCredential. Jakmile se problém vyřeší v budoucí verzi, bude tato změna vrácena.

Moduly plug-in

Azure Identity pro 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. Poskytujeme 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, 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 systému úložiště poskytovaného vaším operačním systémem. Tento modul plug-in umožňuje zachovat hodnoty uložené access_token v mezipaměti napříč relacemi, což znamená, že interaktivní tok přihlášení se nemusí opakovat, dokud je k dispozici token uložený v mezipaměti.

Příklady

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

Ověřte se pomocí DefaultAzureCredential

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

Zadejte spravovanou identitu přiřazenou 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 z toho dělá relativně jednoduchá úloha, která se dá nakonfigurovat pomocí proměnných prostředí nebo v kódu.

Definujte vlastní tok ověřování pomocí ChainedTokenCredential

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

Ověřování spravované identity se podporuje prostřednictvím DefaultAzureCredential tříd přihlašovacích údajů nebo ManagedIdentityCredential 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
• Azure Virtual Machines
• Škálovací sady virtuálních počítačů Azure

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

Konfigurace cloudu

Přihlašovací údaje se ve výchozím nastavení ověřují ve koncovém 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. V cloudu 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,
  }
);

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

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

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

Reference	Využití	Příklad
DefaultAzureCredential	Poskytuje zjednodušené prostředí ověřování pro rychlé zahájení vývoje aplikací spuštěných v Azure.	Příklad
ChainedTokenCredential	Umožňuje uživatelům definovat vlastní toky ověřování s více přihlašovacími údaji.	Příklad
EnvironmentCredential	Ověřuje instanční objekt nebo uživatele pomocí informací o přihlašovacích údajích zadaných v proměnných prostředí.	Příklad
ManagedIdentityCredential	Ověří spravovanou identitu prostředku Azure.	Příklad
WorkloadIdentityCredential	Podporuje ID úlohy Microsoft Entra v Kubernetes.	Příklad

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

Reference	Využití	Příklad	Reference
ClientAssertionCredential	Ověřuje instanční objekt pomocí podepsaného kontrolního výrazu klienta.	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ěří instanční objekt pomocí tajného klíče.	Příklad	Ověřování instančního objektu

Ověřování uživatelů

Reference	Využití	Příklad	Reference
AuthorizationCodeCredential	Ověří 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. Další informace o tom, jak k tomu dochází , najdete tady.	Příklad	Ověřovací kód OAuth2
OnBehalfOfCredential	Šíří identitu delegovaného uživatele a oprávnění prostřednictvím řetězu požadavků.		Ověřování jménem uživatele
UsernamePasswordCredential	Ověří uživatele pomocí uživatelského jména a hesla.	Příklad	Ověřování uživatelským jménem a heslem

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

Reference	Využití	Příklad	Reference
AzureCliCredential	Ověřování ve vývojovém prostředí pomocí Azure CLI	Příklad	Ověřování Azure CLI
AzureDeveloperCliCredential	Ověřování ve vývojovém prostředí pomocí povoleného uživatele nebo instančního objektu v Azure Developer CLI		Referenční informace k Rozhraní příkazového řádku pro vývojáře Azure
AzurePowerShellCredential	Ověřování ve vývojovém prostředí pomocí Azure PowerShellu	Příklad	Ověřování Azure PowerShellu
VisualStudioCodeCredential	Ověří se jako uživatel přihlášený k rozšíření Azure Account pro Visual Studio Code.		Rozšíření VS Code pro účet Azure

Proměnné prostředí

DefaultAzureCredential a EnvironmentCredential lze nakonfigurovat pomocí proměnných 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 klíčů 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 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

Pokus o konfiguraci se provede ve výše uvedeném pořadí. Pokud jsou například k dispozici hodnoty tajného klíče klienta i certifikátu, použije se tajný klíč klienta.

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

Od verze 3.3.0 je přístup k prostředkům chráněným službou CAE (Continuous Access Evaluation ) možný na základě jednotlivých požadavků. To je možné povolit pomocí GetTokenOptions.enableCae(boolean) rozhraní API. U přihlašovacích údajů vývojáře se nepodporuje CAE.

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

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

• Tokeny mezipaměti v paměti (výchozí) a na disku (výslovný souhlas)
• Zvyšte odolnost a výkon.
• Snižte počet požadavků na Microsoft Entra ID za účelem získání přístupových tokenů.

Knihovna identit Azure nabízí ukládání do mezipaměti v pamě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í metodou handshake 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 @azure/identity-broker balíček . Podrobnosti o ověřování pomocí WAM najdete v dokumentaci k modulu plug-in zprostředkovatele.

Poradce při potížích

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

Další kroky

Přečíst si dokumentaci

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

Podpora klientských knihoven

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 jejich dokumentaci, která je propojená na stránce vydaných verzí.

Známé problémy

Podpora Azure AD B2C

Tato knihovna nepodporuje službu Azure AD B2C .

V případě jiných otevřených problémů se podívejte na úložiště GitHub knihovny.

Poskytnutí zpětné vazby

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

Přispívání

Pokud chcete přispívat do této knihovny, přečtěte si příručku pro přispívání , kde najdete další informace o tom, jak sestavit a otestovat kód.