Klientská knihovna Azure Identity pro JavaScript – verze 4.1.0

Knihovna identit Azure poskytuje ověřování tokenů 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
• Microsoft Entra ID dokumentace
• 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 @azure/identity závislost 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 v této knihovně je jediný, InteractiveBrowserCredential který je v prohlížeči podporovaný.

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

Instalace balíčku

Nainstalujte identitu Azure pomocí npm:

npm install --save @azure/identity

Požadavky

• Předplatné Azure
• Volitelné: Azure CLI nebo Azure PowerShell může 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ů vystavené společností @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ě 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ů, které poskytuje, @azure/identity jsou podporovány v Node.js. V prohlížečích je 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é nabízí, @azure/identity 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žené @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á vyhovuje getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null> , fungovat jako TokenCredential. To znamená, že vývojáři můžou psát vlastní typy přihlašovacích údajů pro podporu případů 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í řadu pokročilých případů, vývojáři můžou chtít úplnou kontrolu nad ověřovacím protokolem. V takovém případě 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 @azure/identity použití najdete na stránce Příklady identit Azure .
  • Tam máme konkrétně část Rozšířené příklady .
  • Máme také část, která ukazuje, jak ověřit pomocí MSAL přímo.

V případě pokročilých pracovních postupů ověřování v prohlížeči máme část, ve které ukazujeme, 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ž doporučujeme používat ověřování 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í je možné použít několik vývojářských nástrojů.

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

Vývojáři kódující mimo integrované vývojové prostředí (IDE) 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í.

K ověření pomocí [Azure Developer CLI][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.

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

Ověřování pomocí Azure CLI

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

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 použije příkaz 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ěření prostřednictvím Azure PowerShell

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

Pokud se chcete ověřit pomocí Azure PowerShell uživatelé můžou spustit rutinuConnect-AzAccount. Ve výchozím nastavení spustí azure CLI výchozí webový prohlížeč pro Connect-AzAccount 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í účtu Azure . Aplikace, které používají VisualStudioCodeCredential tento účet, pak můžou tento účet používat k ověřování volání ve své aplikaci při místním spuštění.

Pokud chcete provést ověření 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 .

Navíc použijte balíček modulu plug-in @azure/identity-vscode . 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 verzemi rozšíření účtu Azure novějšími než 0.9.11. Probíhá dlouhodobé řešení tohoto problému. Mezitím zvažte ověřování přes 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 InteractiveBrowserCredentialnástroj , 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 nutné vytvořit registraci Aplikace Azure v Azure Portal pro vaši webovou aplikaci.

Klíčové koncepty

Pokud používáte nebo Microsoft Entra ID poprvé@azure/identity, přečtěte si nejprve téma Používání @azure/identity s Microsoft Entra ID. Tento dokument poskytuje podrobnější informace o platformě a o tom, 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 napříč sadou Azure SDK při vytváření přijímají přihlašovací údaje. 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é jsou schopné 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ých ověřování pomocí TokenCredential.

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

VýchozíAzureCredential

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ěřování při nasazení s přihlašovacími údaji používanými k ověřování ve vývojovém prostředí.

Poznámka: DefaultAzureCredential Má zjednodušit začátek 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žívat jiné typy přihlašovacích údajů.

Pokud se použije z Node.js, DefaultAzureCredential pokusí se ověřit pomocí následujících mechanismů v 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á do 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 Azure PowerShell moduluConnect-AzAccount, ověří se DefaultAzureCredential pomocí daného účtu.
6. Azure Developer CLI – Pokud vývojář ověřil účet pomocí příkazu Azure Developer CLIazd auth login, ověří se DefaultAzureCredential 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
• Azure Virtual Machines Scale Sets

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í v 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 úloh 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ěřte se ve vývojovém prostředí pomocí povoleného uživatele nebo instančního objektu v Azure Developer CLI.		Referenční informace k Azure Developer CLI
AzurePowerShellCredential	Ověřování ve vývojovém prostředí pomocí Azure PowerShell.	Příklad	ověřování Azure PowerShell
VisualStudioCodeCredential	Ověřuje se jako uživatel přihlášený k rozšíření účtu Azure v editoru Visual Studio Code.		Rozšíření účtu Azure pro VS Code

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 uživatele

Konfigurace se pokusí ve výše uvedeném pořadí. Pokud jsou například k dispozici hodnoty pro tajný klíč klienta i pro certifikát, 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. Certifikační autorita není podporovaná 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á 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 o 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ě je podporován 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é 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ímat 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.

Další otevřené problémy najdete v úložišti GitHubu v knihovně.

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 prosím průvodce přispívání , kde se dozvíte více o tom, jak sestavit a otestovat kód.