Azure Identity-ügyfélkódtár JavaScripthez – 4.8.0-s verzió

Az Azure Identity-kódtár kényelmes TokenCredential implementációkon keresztül biztosítja Microsoft Entra ID (korábbi nevén Azure Active Directory) jogkivonat-hitelesítést.

A különböző hitelesítő adatokra vonatkozó példákért tekintse meg az Azure Identity példák lapját.

Főbb hivatkozások:

• Forráskód
• Csomag (npm)
• API referenciadokumentációja
• Microsoft Entra Azonosító dokumentáció
• Példák

Kezdetekhez

Jelenleg támogatott környezetek

• A Node.js LTS-verziói
• A Safari, a Chrome, az Edge és a Firefox legújabb verziói.
  • Megjegyzés: A tárban exportált különböző hitelesítő adatok közül InteractiveBrowserCredential az egyetlen, amelyet a böngésző támogat.

További információ: támogatási szabályzat.

A csomag telepítése

Az Azure Identity telepítése npm:

npm install --save @azure/identity

Előfeltételek

• Egy Azure-előfizetés.
• Nem kötelező: Az Azure CLI és/vagy Azure PowerShell- is hasznosak lehetnek a fejlesztési környezetben való hitelesítéshez és a fiókszerepkörök kezeléséhez.

Mikor érdemes használni a @azure/identity

A @azure/identity által közzétett hitelesítő adatok osztályai arra összpontosítanak, hogy a legegyszerűbb módot kínálják az Azure SDK-ügyfelek helyi, fejlesztői környezetekben és éles környezetben történő hitelesítésére. A hitelesítési protokollok egyszerűségére és ésszerű támogatására törekszünk, hogy lefedjük az Azure-ban lehetséges legtöbb hitelesítési forgatókönyvet. Aktívan bővítjük a további forgatókönyveket. A felajánlott hitelesítő adatok teljes listáját a Hitelesítő adatok osztályai szakaszban találja.

Az @azure/identity által biztosított hitelesítőadat-típusokat a Node.jstámogatja. A böngészők esetében a InteractiveBrowserCredential az alapszintű hitelesítési forgatókönyvekhez használandó hitelesítő adattípus.

Az @azure/identity által kínált hitelesítő adatok többsége a JavaScripthez készült Microsoft Authentication Library (MSAL.js)használja. Pontosabban a V2 MSAL.js kódtárakat használjuk, amelyek OAuth 2.0 engedélyezési kódfolyamot használnak a PKCE, és OpenID-kompatibilis. Bár @azure/identity az egyszerűségre összpontosít, a MSAL.js kódtárak, például a @azure/msal-common, a @azure/msal-nodeés a @azure/msal-browser, robusztus támogatást nyújtanak az Azure által támogatott hitelesítési protokollokhoz.

Mikor érdemes valami mást használni?

A @azure/identity hitelesítő adatok a @azure/core-authTokenCredential osztály implementációi. Elvben minden olyan getToken metódussal rendelkező objektum, amely megfelel a getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null>TokenCredentialműködik. Ez azt jelenti, hogy a fejlesztők saját hitelesítőadat-típusokat írhatnak, hogy támogassák a @azure/identityáltal nem érintett hitelesítési eseteket. További információ: egyéni hitelesítő adatok.

Bár a hitelesítő adatok típusai számos speciális forgatókönyvet támogatnak, a fejlesztők JavaScripthez készült Microsoft Authentication Library (MSAL.js) közvetlenül szeretnének használni. Fontolja meg a MSAL.js használatát a következő helyzetekben:

• Azok a fejlesztők, akik teljes mértékben ellenőrizni szeretnék a hitelesítési protokollt és annak konfigurációját.
• Hitelesítő adattípusaink úgy vannak kialakítva, hogy az Azure SDK-ügyfelekhez használhatóak legyenek intelligens gyorsítótárazással és jogkivonat-frissítéssel a fő HTTP-rétegben. Ha úgy találja, hogy közvetlenül getToken kell használnia, a MSAL.js használatával jobban szabályozhatja a hitelesítési folyamatot és a tokenek gyorsítótárazását.

További információkért tekintse meg az alábbi hivatkozásokat:

• Az @azure/identity oldalán mutatjuk be a néhány speciális használati esetét.
  • Itt külön Speciális példák szakaszunk van.
  • Van egy szakaszunk is, amely bemutatja, hogyan hitelesítést közvetlenül az MSAL használatával.

A böngésző speciális hitelesítési munkafolyamataihoz egy szakaszt mutatunk be, amely bemutatja, hogyan használhatja közvetlenül a @azure/msal-browser kódtárat az Azure SDK-ügyfelek hitelesítéséhez.

Az ügyfél hitelesítése fejlesztési környezetben

Bár azt javasoljuk, hogy felügyelt identitást használjon az Azure-ban üzemeltetett alkalmazásban, a fejlesztők általában a saját fiókjukat használják az Azure-szolgáltatásokba irányuló hívások hitelesítéséhez a kód helyi hibakeresése és végrehajtása során. A fejlesztési környezetben számos fejlesztői eszköz használható a hitelesítés végrehajtásához.

Hitelesítés az Azure Developer CLI-vel

Az IDE-n kívül kódoló fejlesztők az Azure Developer CLI- is használhatják a hitelesítéshez. A DefaultAzureCredential vagy a AzureDeveloperCliCredential használó alkalmazások ezt a fiókot használhatják az alkalmazáson belüli hívások hitelesítésére helyi futtatáskor.

Az Azure Developer CLIhitelesítéséhez a felhasználók futtathatják a parancsot. Az alapértelmezett webböngészővel rendelkező rendszeren futó felhasználók esetében az Azure Developer CLI elindítja a böngészőt a felhasználó hitelesítéséhez.

Az alapértelmezett webböngészővel nem rendelkező rendszerek esetében a azd auth login --use-device-code parancs az eszközkód-hitelesítési folyamatot használja.

Hitelesítés az Azure CLI-vel

A AzureCliCredentialhasználó alkalmazások – akár közvetlenül, akár a DefaultAzureCredentialkeresztül – az Azure CLI-fiókkal hitelesíthetik az alkalmazásban lévő hívásokat helyi futtatáskor.

Az Azure CLIhitelesítéséhez futtassa a parancsot . Az alapértelmezett webböngészővel rendelkező rendszeren futó felhasználók esetében az Azure CLI elindítja a böngészőt a felhasználó hitelesítéséhez.

Az alapértelmezett webböngészővel nem rendelkező rendszerek esetében a az login parancs az eszközkód-hitelesítési folyamatot használja. A felhasználó a --use-device-code argumentum megadásával arra is kényszerítheti az Azure CLI-t, hogy használja az eszköz kódfolyamatát a böngésző elindítása helyett.

Hitelesítés az Azure PowerShell használatával

A AzurePowerShellCredentialhasználó alkalmazások – akár közvetlenül, akár a DefaultAzureCredentialkeresztül – használhatják az Azure PowerShell-hez csatlakoztatott fiókot a helyi futtatáskor az alkalmazásban lévő hívások hitelesítéséhez.

Ha Azure PowerShell-szeretne hitelesíteni, futtassa a Connect-AzAccount parancsmagot. Alapértelmezés szerint az Azure CLI-hez Connect-AzAccount hasonlóan elindítja az alapértelmezett webböngészőt egy felhasználói fiók hitelesítéséhez.

Ha az interaktív hitelesítés nem támogatott a munkamenetben, akkor a -UseDeviceAuthentication argumentum arra kényszeríti a parancsmagot, hogy inkább eszközkód-hitelesítési folyamatot használjon, hasonlóan az Azure CLI-hitelesítő adatok megfelelő beállításához.

Az ügyfél hitelesítése böngészőkben

Az Azure SDK-ügyfelek webböngészőn belüli hitelesítéséhez kínáljuk a InteractiveBrowserCredential, amely beállítható átirányítás vagy előugró ablakok használatára a hitelesítési folyamat befejezéséhez. Először létre kell hoznia egy Azure-alkalmazásregisztrációs az Azure Portalon a webalkalmazás számára.

Főbb fogalmak

Ha először használja @azure/identity vagy Microsoft Entra-azonosítót, olvassa el A @azure/identity használata a Microsoft Entra-azonosítóval című cikket. Ez a dokumentum részletesebben ismerteti a platformot és az Azure-fiók helyes konfigurálását.

Megbízólevél

A hitelesítő adatok olyan osztályok, amelyek tartalmazzák vagy lekérhetik a kérések hitelesítéséhez szükséges adatokat a szolgáltatásügyfél számára. A szolgáltatás ügyfelei az Azure SDK-ban fogadják el a hitelesítő adatokat a létrehozásakor. A szolgáltatás ügyfelei ezeket a hitelesítő adatokat használják a szolgáltatáshoz érkező kérések hitelesítéséhez.

Az Azure Identity-kódtár a Microsoft Entra ID-val történő OAuth-hitelesítésre összpontosít, és különböző hitelesítő osztályokat kínál, amelyek képesek Microsoft Entra-jogkivonat beszerzésére a szolgáltatáskérések hitelesítéséhez. A kódtárban található összes hitelesítő osztály a TokenCredential absztrakt osztály implementációja, és bármelyiket használhatja olyan szolgáltatásügyfelek létrehozásához, amelyek képesek hitelesíteni egy TokenCredential.

Lásd: hitelesítő adatok osztályai.

DefaultAzureCredential

DefaultAzureCredential leegyszerűsíti a hitelesítést az Azure-ban üzembe helyező alkalmazások fejlesztése során az Azure-ban használt hitelesítő adatok és a helyi fejlesztés során használt hitelesítő adatok kombinálásával. További információt a DefaultAzureCredential áttekintésében talál.

Folytatási szabályzat

A 3.3.0-s verziótól DefaultAzureCredential az összes fejlesztői hitelesítő adattal megkísérli a hitelesítést, amíg az egyik sikeres nem lesz, függetlenül a korábbi fejlesztői hitelesítő adatokkal tapasztalt hibáktól. Előfordulhat például, hogy a fejlesztői hitelesítő adatok jogkivonatot próbálnak lekérni, és sikertelenek lesznek, így DefaultAzureCredential továbbra is a folyamat következő hitelesítő adatai lesznek. Az üzembe helyezett szolgáltatás hitelesítő adatai kivétel nélkül leálltatják a folyamatot, ha meg tudják kísérelni a jogkivonatok lekérését, de nem kapnak egyet.

Ez lehetővé teszi az összes fejlesztői hitelesítő adat kipróbálását a gépen, miközben kiszámítható üzembe helyezési viselkedéssel rendelkezik.

Megjegyzés a VisualStudioCodeCredential

Egy ismert probléma miatt, VisualStudioCodeCredential el lett távolítva a DefaultAzureCredential jogkivonatláncból. Ha a probléma egy későbbi kiadásban lesz megoldva, a rendszer visszaállítja ezt a módosítást.

Beépülő modulok

Az Azure Identity for JavaScript egy beépülő modul API-t biztosít, amely lehetővé teszi bizonyos funkciók biztosítását külön beépülő modulcsomagok. A @azure/identity csomag exportál egy legfelső szintű függvényt (useIdentityPlugin), amely beépülő modul engedélyezésére használható. Két beépülő modulcsomagot biztosítunk:

• @azure/identity-broker, amely egy natív közvetítőn keresztül, például a Web Account Manageren keresztül biztosít közvetítőalapú hitelesítést.
• @azure/identity-cache-persistence, amely állandó jogkivonat-gyorsítótárazást biztosít Node.js az operációs rendszer által biztosított natív biztonságos tárolórendszer használatával. Ez a beépülő modul lehetővé teszi a gyorsítótárazott access_token értékek munkamenetek közötti megőrzését, ami azt jelenti, hogy az interaktív bejelentkezési folyamatot nem kell megismételni, amíg elérhető a gyorsítótárazott jogkivonat.

Példák

További példákat találhat a különböző hitelesítő adatok használatára Azure Identity Examples page

Hitelesítés DefaultAzureCredential

Ez a példa a KeyClient hitelesítését mutatja be a @azure/keyvault-keys ügyfélkódtárból DefaultAzureCredentialhasználatával.

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);

Felhasználó által hozzárendelt felügyelt identitás megadása DefaultAzureCredential

Egy viszonylag gyakori forgatókönyv magában foglalja a felhasználó által hozzárendelt felügyelt identitás azure-erőforrásokhoz való hitelesítését. Tekintse meg a példát a felhasználó által hozzárendelt felügyelt identitás defaultAzureCredential hitelesítésére, és ismerje meg, hogyan történik ez egy viszonylag egyszerű feladat, amely környezeti változókkal vagy kóddal konfigurálható.

Egyéni hitelesítési folyamat definiálása ChainedTokenCredential

Bár a DefaultAzureCredential általában a leggyorsabb módszer az Azure-alkalmazások fejlesztésének megkezdésére, a fejlettebb felhasználók érdemes lehet testre szabni a hitelesítés során figyelembe vett hitelesítő adatokat. A ChainedTokenCredential lehetővé teszi, hogy a felhasználók több hitelesítő példányt egyesítsenek a hitelesítő adatok testreszabott láncának meghatározásához. Ez a példa egy olyan ChainedTokenCredential létrehozását mutatja be, amely a ClientSecretCredentialkét eltérően konfigurált példányával próbál hitelesíteni, majd hitelesíteni a KeyClient a @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);

Felügyelt identitás támogatása

A felügyelt identitáshitelesítési közvetlenül a DefaultAzureCredential vagy a ManagedIdentityCredential hitelesítő osztályokon keresztül támogatott közvetlenül az alábbi Azure-szolgáltatásokhoz:

• Azure App Service és Azure Functions
• Azure Arc
• Azure Cloud Shell
• Azure Kubernetes Service
• Azure Service Fabric
• Azure Virtual Machines
• Azure-beli virtuálisgép-méretezési csoportok

A felügyelt identitás hitelesítéshez való használatára vonatkozó példákért lásd a példákat.

Felhőkonfiguráció

Az Azure Public Cloud Microsoft Entra-végpontjának hitelesítéséhez alapértelmezett hitelesítő adatok. Más felhőkben, például az Azure Governmentben vagy egy magánfelhőben lévő erőforrások eléréséhez konfigurálja a hitelesítő adatokat a konstruktor authorityHost argumentumával. A AzureAuthorityHosts enumerálás meghatározza a jól ismert felhők hatóságait. Az USA kormányzati felhőjéhez a következő módon hozhat létre hitelesítő adatokat:

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

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

A authorityHost argumentum megadásának alternatívájaként beállíthatja a AZURE_AUTHORITY_HOST környezeti változót a felhő szolgáltatójának URL-címére is. Ez a módszer akkor hasznos, ha több hitelesítő adatot konfigurál ugyanazon a felhőn való hitelesítéshez, vagy ha az üzembe helyezett környezetnek meg kell határoznia a célfelhőt:

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

A AzureAuthorityHosts enumerálás a jól ismert felhők hatóságait határozza meg az Ön kényelme érdekében; Ha azonban a felhő szolgáltatója nem szerepel a AzureAuthorityHostslistán, akkor karakterlánc argumentumként bármely érvényes szolgáltatói URL-címet átadhat. Példa:

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

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

Nem minden hitelesítő adat igényli ezt a konfigurációt. A fejlesztőeszközön (például AzureCliCredential) keresztül hitelesítő hitelesítő adatok az eszköz konfigurációját használják. Hasonlóképpen, VisualStudioCodeCredential elfogad egy authorityHost argumentumot, de alapértelmezés szerint az authorityHost a Visual Studio Code Azure: Cloud beállításának felel meg.

Hitelesítő adatok osztályai

Hitelesítőadat-láncok

Azure által üzemeltetett alkalmazások hitelesítése

Szolgáltatásnevek hitelesítése

Felhasználók hitelesítése

Hitelesítés fejlesztői eszközökkel

Környezeti változók

DefaultAzureCredential és EnvironmentCredential környezeti változókkal konfigurálhatók. Minden hitelesítési típushoz szükség van bizonyos változók értékeire.

Szolgáltatásnév titkos kóddal

Szolgáltatásnév tanúsítvánnyal

A konfigurációt a rendszer az előző sorrendben kísérli meg. Ha például az ügyfélkulcs és a tanúsítvány értékei is jelen vannak, a rendszer az ügyfélkulcsot használja.

Folyamatos hozzáférés kiértékelése

A 3.3.0-s verziótól kezdődően a folyamatos hozzáférés-kiértékelési (CAE) által védett erőforrások hozzáférése kérésenként lehetséges. Ez a GetTokenOptions.enableCae(boolean) APIhasználatával engedélyezhető. A CAE nem támogatott a fejlesztői hitelesítő adatok esetében.

Jogkivonat gyorsítótárazása

A tokenek gyorsítótárazása az Azure Identity-kódtár által biztosított szolgáltatás, amely lehetővé teszi az alkalmazások számára a következőket:

• Gyorsítótár-jogkivonatok a memóriában (alapértelmezett) és a lemezen (opt-in).
• A rugalmasság és a teljesítmény javítása.
• Csökkentse a Microsoft Entra ID-nak küldött kérések számát a hozzáférési jogkivonatok beszerzéséhez.

Az Azure Identity-kódtár a memóriában és az állandó lemez gyorsítótárazását is biztosítja. További információ: token gyorsítótárazási dokumentációja.

Közvetített hitelesítés

A hitelesítési közvetítő egy olyan alkalmazás, amely egy felhasználó gépén fut, és kezeli a csatlakoztatott fiókok hitelesítési kézfogásait és tokenkarbantartását. Jelenleg csak a Windows Web Account Manager (WAM) támogatott. A támogatás engedélyezéséhez használja a @azure/identity-broker csomagot. A WAM használatával történő hitelesítéssel kapcsolatos részletekért tekintse meg a közvetítő beépülő modul dokumentációját.

Hibaelhárítás

A hibaelhárítással kapcsolatos segítségért tekintse meg a hibaelhárítási útmutatót.

Következő lépések

A dokumentáció elolvasása

A kódtár API-dokumentációja a dokumentációs webhelyén.

Ügyféloldali kódtár támogatása

Az Azure SDK kiadási lapján felsorolt ügyfél- és felügyeleti kódtárak, amelyek támogatják a Microsoft Entra-hitelesítést, fogadják el a tár hitelesítő adatait. További információ ezekről a kódtárakról a kiadási oldalról csatolt dokumentációban.

Ismert problémák

Az Azure AD B2C támogatása

Ez a kódtár nem támogatja az Azure AD B2C szolgáltatás .

További nyitott problémákért tekintse meg a tár GitHub-adattár.

Visszajelzés küldése

Ha hibákat tapasztal, vagy javaslatai vannak, nyisson meg egy problémát.

Hozzájárulás

Ha hozzá szeretne járulni ehhez a kódtárhoz, olvassa el a közreműködői útmutatót, hogy többet tudjon meg a kód összeállításáról és teszteléséről.