Řetězy přihlašovacích údajů v knihovně Identit Azure pro JavaScript

Knihovna Identit Azure poskytuje přihlašovací údaje– veřejné třídy, které implementují rozhraní TokenCredential knihovny Azure Core. Přihlašovací údaje představují jedinečný tok ověřování pro získání přístupového tokenu z ID Microsoft Entra. Tyto přihlašovací údaje je možné zřetězit dohromady, aby tvořily seřazenou posloupnost ověřovacích mechanismů, které mají být použity.

Jak fungují zřetězené přihlašovací údaje

Během spuštění se řetěz přihlašovacích údajů pokusí ověřit pomocí prvních přihlašovacích údajů v pořadí. Pokud se tento přihlašovací údaj nepodaří získat přístupový token, pokusí se další přihlašovací údaje v této sekvenci atd., dokud se přístupový token úspěšně nezíská. Toto chování znázorňuje následující sekvenční diagram:

Diagram sekvence řetězu přihlašovacích údajů znázorňující pokusy o ověření procházející více přihlašovacími údaji, dokud se přístupový token nezíská.

Proč používat řetězy přihlašovacích údajů

Zřetězené přihlašovací údaje mohou nabídnout následující výhody:

Rozpoznávání prostředí: Automaticky vybere nejvhodnější přihlašovací údaje na základě prostředí, ve kterém je aplikace spuštěná. Bez něj byste museli psát kód takto:

import { 
    ManagedIdentityCredential, 
    AzureCliCredential 
} from "@azure/identity";

let credential;
if (process.env.NODE_ENV === "production") {
    credential = new ManagedIdentityCredential();
} else {
    credential = new AzureCliCredential();
}

Bezproblémové přechody: Aplikace se může přesunout z místního vývoje do přípravného nebo produkčního prostředí beze změny ověřovacího kódu.
Vylepšená odolnost: Zahrnuje náhradní mechanismus, který se přesune na další přihlašovací údaje, když se předchozí pokus o získání přístupového tokenu nezdaří.

Jak vybrat zřetězené přihlašovací údaje

Existují dva různé přístupy k řetězení autentizačních údajů:

"Rozebrat" řetěz: Začněte s předkonfigurovaným řetězem a odstraňte, co nepotřebujete. Tento přístup najdete v části Přehled DefaultAzureCredential.
"Sestavte" řetězec: Začněte prázdným řetězem a zahrňte pouze to, co potřebujete. Tento přístup naleznete v části Přehled ChainedTokenCredential.

Přehled DefaultAzureCredential

DefaultAzureCredential je předkonfigurovaný řetězec přihlašovacích údajů s pevně stanovenými preferencemi. Je navržená tak, aby podporovala mnoho prostředí spolu s nejběžnějšími toky ověřování a vývojářskými nástroji. Základní řetězec v grafické podobě vypadá takto:

Pořadí, ve kterém DefaultAzureCredential použije přihlašovací údaje, je následující.

Objednávka	Pověření	Popis	Povoleno ve výchozím nastavení?
1	prostředí	Načte kolekci proměnných prostředí k určení, jestli je pro aplikaci nakonfigurovaný servisní principál (uživatel aplikace). Pokud ano, `DefaultAzureCredential` tyto hodnoty použije k ověření aplikace v Azure. Tato metoda se nejčastěji používá v serverových prostředích, ale dá se použít také při místním vývoji.	Ano
2	identita pracovního zatížení	Pokud je aplikace nasazená na hostitele Azure s povolenou identitou úloh, ověřte tento účet.	Ano
3	spravované identity	Pokud je aplikace nasazená na hostitele Azure s povolenou spravovanou identitou, ověřte ji v Azure pomocí této spravované identity.	Ano
4	Visual Studio Code	Pokud se vývojář ověřil prostřednictvím rozšíření Azure Resources editoru Visual Studio Code a je nainstalovaný balíček @azure/identity-vscode , ověřte tento účet.	Ano
5	Azure CLI	Pokud se vývojář ověřil v Azure pomocí příkazu azure CLI `az login`, ověřte aplikaci v Azure pomocí stejného účtu.	Ano
6	Azure PowerShell	Pokud se vývojář ověřil v Azure pomocí `Connect-AzAccount` rutiny Azure PowerShellu, ověřte aplikaci v Azure pomocí stejného účtu.	Ano
7	Azure Developer CLI	Pokud se vývojář ověřil v Azure pomocí `azd auth login` příkazu Azure Developer CLI, ověřte ho pomocí daného účtu.	Ano
8	zprostředkovatel	Ověřuje se pomocí výchozího účtu přihlášeného k operačnímu systému prostřednictvím zprostředkovatele. Vyžaduje, aby byl nainstalován balíček @azure/identity-broker .	Ano

V nejjednodušší podobě můžete použít bezparametrovou verzi DefaultAzureCredential následujícím způsobem:

import { DefaultAzureCredential } from "@azure/identity";
import { BlobServiceClient } from "@azure/storage-blob";

// Acquire a credential object
const credential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
    `https://${storageAccountName}.blob.core.windows.net`,
    credential
);

Jak přizpůsobit DefaultAzureCredential

Následující části popisují strategie pro řízení, které přihlašovací údaje jsou zahrnuty v řetězci.

Vyloučení kategorie typu přihlašovacích údajů

Chcete-li vyloučit všechny přihlašovací údaje Developer tool nebo Deployed service, nastavte proměnnou prostředí AZURE_TOKEN_CREDENTIALS na prod nebo dev. Pokud se použije hodnota prod, základní řetězec přihlašovacích údajů vypadá takto:

Diagram sekvence řetězu přihlašovacích údajů znázorňující pokusy o ověření procházející více přihlašovacími údaji, dokud se přístupový token nezíská.

Pokud se použije hodnota dev , řetězec vypadá takto:

Diagram výchozího řetězce DefaultAzureCredential s AZURE_TOKEN_CREDENTIALS nastaveným na dev a zobrazující přihlašovací údaje nástroje pro vývojáře používané k ověřování

Chcete-li zajistit, aby byla proměnná prostředí definována a nastavena na podporovaný řetězec, nastavte požadovanou vlastnostEnvVars na AZURE_TOKEN_CREDENTIALS:

const credential = new DefaultAzureCredential({ 
    requiredEnvVars: [ "AZURE_TOKEN_CREDENTIALS" ]
});

Použití konkrétních přihlašovacích údajů

Pokud chcete vyloučit všechny přihlašovací údaje kromě jednoho, nastavte proměnnou AZURE_TOKEN_CREDENTIALS prostředí na název přihlašovacích údajů. Můžete například zmenšit řetěz DefaultAzureCredential na AzureCliCredential tím, že nastavíte AZURE_TOKEN_CREDENTIALS na AzureCliCredential. Porovnání řetězců se provádí bez rozlišování velkých a malých písmen. Platné řetězcové hodnoty pro proměnnou prostředí zahrnují:

AzureCliCredential
AzureDeveloperCliCredential
AzurePowerShellCredential
EnvironmentCredential
ManagedIdentityCredential
VisualStudioCodeCredential
WorkloadIdentityCredential

Důležité

AZURE_TOKEN_CREDENTIALS Proměnná prostředí podporuje jednotlivé názvy přihlašovacích údajů ve @azure/identity verzích balíčku 4.11.0 a novějších.

Pokud chcete zajistit, aby byla proměnná prostředí definována a nastavena na podporovaný řetězec, nastavte vlastnost requiredEnvVars na AZURE_TOKEN_CREDENTIALS:

const credential = new DefaultAzureCredential({ 
    requiredEnvVars: [ "AZURE_TOKEN_CREDENTIALS" ]
});

Přehled ChainedTokenCredential

ChainedTokenCredential je prázdný řetězec, ke kterému přidáte přihlašovací údaje podle potřeb vaší aplikace. Například:

import { 
    ChainedTokenCredential, 
    AzureCliCredential, 
    VisualStudioCodeCredential 
} from "@azure/identity";

const credential = new ChainedTokenCredential(
    new AzureCliCredential(),
    new VisualStudioCodeCredential()
);

const blobServiceClient = new BlobServiceClient(
    `https://${storageAccountName}.blob.core.windows.net`,
    credential
);

Předchozí ukázka kódu vytvoří přizpůsobený řetěz přihlašovacích údajů složený ze dvou přihlašovacích údajů v době vývoje. Nejprve se provede AzureCliCredential, a pokud je to nutné, následuje VisualStudioCodeCredential. V grafické podobě řetězec vypadá takto:

Diagram řetězu přihlašovacích údajů zobrazující AzureCliCredential jako první pokus a VisualStudioCodeCredential jako náhradní

Spropitné

Pokud chcete dosáhnout vyššího výkonu, optimalizujte řazení přihlašovacích údajů v ChainedTokenCredential od většiny po nejméně používané přihlašovací údaje.

Pokyny k použití pro DefaultAzureCredential

DefaultAzureCredential je nepochybně nejjednodušší způsob, jak začít s knihovnou identit Azure, ale toto pohodlí s sebou přináší i určitá omezení. Po nasazení aplikace do Azure byste měli porozumět požadavkům na ověřování aplikace. Z tohoto důvodu nahraďte DefaultAzureCredential konkrétní implementací TokenCredential, například ManagedIdentityCredential.

Tady je důvod:

Výzvy při ladění: Při selhání ověřování může být náročné ladit a identifikovat chybné přihlašovací údaje. Abyste viděli průběh z jednoho pověření na další a stav úspěchu/selhání každého z nich, musíte povolit protokolování. Další informace naleznete v tématu Ladění přihlašovacích údajů.
Výkonová režie: Proces postupného zkoušení více přihlašovacích údajů může představovat výkonovou režii. Například při spuštění na místním vývojovém počítači není spravovaná identita k dispozici. V důsledku toho ManagedIdentityCredential vždy selže v místním vývojovém prostředí.
Nepředvídatelné chování: DefaultAzureCredential kontroluje přítomnost určitých proměnných prostředí. Je možné, že někdo může přidat nebo upravit tyto proměnné prostředí na úrovni systému na hostitelském počítači. Tyto změny platí globálně a proto mění chování DefaultAzureCredential za běhu v libovolné aplikaci spuštěné na tomto počítači.

Ladit přihlašovací údaje

Pokud chcete diagnostikovat neočekávaný problém nebo zjistit, co přihlašovací údaje dělají, povolte protokolování v aplikaci. Například:

import { setLogLevel, AzureLogger } from "@azure/logger";
import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

// Constant for the Azure Identity log prefix
const AZURE_IDENTITY_LOG_PREFIX = "azure:identity";

// override logging to output to console.log (default location is stderr)
// only log messages that start with the Azure Identity log prefix
setLogLevel("verbose");
AzureLogger.log = (...args) => {
  const message = args[0];
  if (typeof message === 'string' && message.startsWith(AZURE_IDENTITY_LOG_PREFIX)) {
    console.log(...args);
  }
};

// Get storage account name from environment variable
const storageAccountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;

if (!storageAccountName) {
    throw new Error("AZURE_STORAGE_ACCOUNT_NAME environment variable is required");
}

const credential = new DefaultAzureCredential({ 
    requiredEnvVars: [ "AZURE_TOKEN_CREDENTIALS" ]
});


const blobServiceClient = new BlobServiceClient(
    `https://${storageAccountName}.blob.core.windows.net`,
    credential
);

azure:identity:info EnvironmentCredential => Found the following environment variables: 
azure:identity:verbose EnvironmentCredential => AZURE_CLIENT_SEND_CERTIFICATE_CHAIN: undefined; sendCertificateChain: false
azure:identity:info WorkloadIdentityCredential => Found the following environment variables:
azure:identity:warning DefaultAzureCredential => Skipped createDefaultWorkloadIdentityCredential because of an error creating the credential: CredentialUnavailableError: WorkloadIdentityCredential: is unavailable. clientId is a required parameter. In DefaultAzureCredential and ManagedIdentityCredential, this can be provided as an environment variable - "AZURE_CLIENT_ID".
        See the troubleshooting guide for more information: https://aka.ms/azsdk/js/identity/workloadidentitycredential/troubleshoot
azure:identity:info ManagedIdentityCredential => Using DefaultToImds managed identity.
azure:identity:warning DefaultAzureCredential => Skipped createDefaultBrokerCredential because of an error creating the credential: Error: Broker for WAM was requested, but no plugin was configured or no authentication record was found. You must install the @azure/identity-broker plugin package (npm install --save @azure/identity-broker) and enable it by importing `useIdentityPlugin` from `@azure/identity` and calling useIdentityPlugin(nativeBrokerPlugin) before using enableBroker.
azure:identity:info DefaultAzureCredential => getToken() => Skipping createDefaultWorkloadIdentityCredential, reason: WorkloadIdentityCredential: is unavailable. clientId is a required parameter. In DefaultAzureCredential and ManagedIdentityCredential, this can be provided as an environment variable - "AZURE_CLIENT_ID".
        See the troubleshooting guide for more information: https://aka.ms/azsdk/js/identity/workloadidentitycredential/troubleshoot
azure:identity:info ManagedIdentityCredential => getToken() => Using the MSAL provider for Managed Identity.
azure:identity:info ManagedIdentityCredential - Token Exchange => ManagedIdentityCredential - Token Exchange: Unavailable. The environment variables needed are: AZURE_CLIENT_ID (or the client ID sent through the parameters), AZURE_TENANT_ID and AZURE_FEDERATED_TOKEN_FILE
azure:identity:info ManagedIdentityCredential => getToken() => MSAL Identity source: DefaultToImds
azure:identity:info ManagedIdentityCredential => getToken() => Using the IMDS endpoint to probe for availability.
azure:identity:info ManagedIdentityCredential - IMDS => ManagedIdentityCredential - IMDS: Pinging the Azure IMDS endpoint
azure:identity:verbose ManagedIdentityCredential - IMDS => ManagedIdentityCredential - IMDS: Caught error RestError: connect ENETUNREACH 169.254.169.254:80
azure:identity:info ManagedIdentityCredential - IMDS => ManagedIdentityCredential - IMDS: The Azure IMDS endpoint is unavailable
azure:identity:error ManagedIdentityCredential => getToken() => ERROR. Scopes: https://storage.azure.com/.default. Error message: Attempted to use the IMDS endpoint, but it is not available..
azure:identity:info AzureCliCredential => getToken() => Using the scope https://storage.azure.com/.default
azure:identity:info AzureCliCredential => getToken() => expires_on is available and is valid, using it
azure:identity:info AzureCliCredential => getToken() => SUCCESS. Scopes: https://storage.azure.com/.default.

V předchozím výstupu si všimněte, že DefaultAzureCredential token úspěšně získal pomocí AzureCliCredential.

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-10-10