Klientská knihovna Azure Identity pro JavaScript – verze 4.5.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ý kód
• Balíček (npm)
• Referenční dokumentace k rozhraní API
• Microsoft Entra ID dokumentace
• Ukázky

Začínáme

Aktuálně podporovaná prostředí

• Verze LTS Node.js
• 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ým podporovaným v prohlížeči.

Další informace najdete v našich zásad 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 atribut @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> funguje 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 scénářů, vývojáři možná budou chtít místo toho použít knihovnu Microsoft Authentication Library pro JavaScript (MSAL.js). Zvažte použití MSAL.js v následujících scénářích:

• Vývojáři, kteří chtějí mít plnou kontrolu nad ověřovacím protokolem a jeho konfigurací
• Naše typy přihlašovacích údajů jsou navržené tak, aby se používaly s klienty Azure SDK s inteligentním ukládáním do mezipaměti a aktualizací tokenů zpracovanými v základní vrstvě HTTP. Pokud zjistíte, že getToken budete muset používat přímo, můžete využít MSAL.js, abyste měli větší kontrolu nad tokem ověřování a ukládáním tokenů do mezipaměti.

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ář při ladění a místním spouštění kódu používá vlastní účet pro ověřování volání služeb Azure. 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 azure Developer CLI spustí prohlížeč pro ověření uživatele.

Pro systémy bez výchozího webového prohlížeče používá 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.

Pokud se chcete ověřit pomocíAzure CLI , spusťte příkaz . 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žívá 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, spusťte rutinu Connect-AzAccount. Ve výchozím nastavení, jako je Azure CLI, spustí výchozí webový prohlížeč pro Connect-AzAccount ověření uživatelského účtu.

Pokud interaktivní ověřování není možné v relaci podporovat, pak -UseDeviceAuthentication argument vynutí rutinu, aby místo toho používala tok ověřování 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 s ID Microsoft Entra a nabízí různé třídy 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 pověření 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 zjednodušuje ověřování při vývoji aplikací, které se nasazují do Azure, kombinováním přihlašovacích údajů používaných v hostitelských prostředích Azure s přihlašovacími údaji používanými v místním vývoji. Další informace naleznete v tématu DefaultAzureCredential přehled.

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. Například přihlašovací údaje vývojáře se mohou pokusit získat token a selhat, takže DefaultAzureCredential pokračovat k dalším přihlašovacím údajům v toku. Nasazené přihlašovací údaje služby zastavují 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, pokud 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ěření KeyClient z klientské knihovny @azure/keyvault-keys pomocí 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);

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ž DefaultAzureCredential je 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";
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);

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:

• služba Aplikace Azure 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é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. Výčet 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 { ClientSecretCredential, AzureAuthorityHosts } from "@azure/identity";

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

Jako alternativu k zadání argumentu authorityHost můžete také nastavit proměnnou prostředí AZURE_AUTHORITY_HOST na adresu URL autority vašeho cloudu. Tento přístup je užitečný při konfiguraci více přihlašovacích údajů pro ověření ve stejném cloudu nebo v případě, že nasazené prostředí potřebuje definovat cílový cloud:

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

Výčet AzureAuthorityHosts definuje autority pro dobře známé cloudy pro vaše pohodlí; Pokud ale autorita pro váš cloud není uvedená v AzureAuthorityHosts, můžete jako řetězcový argument předat platnou adresu URL autority. Příklad:

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

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

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ů

Řetězy přihlašovacích údajů

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

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

Pověření	Zvyk	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í přes 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	(volitelné) heslo souboru certifikátu, pokud existuje
AZURE_CLIENT_SEND_CERTIFICATE_CHAIN	(volitelné) Odeslání řetězu certifikátů v hlavičce x5c za účelem podpory názvu subjektu nebo ověřování na základě vystavitele

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ší v předchozí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ší informace 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 tom, jak sestavit a otestovat kód.