Łańcuchy poświadczeń w bibliotece tożsamości platformy Azure dla języka JavaScript

Biblioteka tożsamości platformy Azure udostępnia poświadczenia — klasy publiczne, które implementują interfejs TokenCredential biblioteki Azure Core. Poświadczenie reprezentuje odrębny przepływ uwierzytelniania na potrzeby uzyskiwania tokenu dostępu z identyfikatora Entra firmy Microsoft. Te poświadczenia można połączyć w łańcuch, aby utworzyć uporządkowaną sekwencję mechanizmów uwierzytelniania, które należy zastosować.

Jak działa poświadczenie łańcuchowe

Podczas wykonywania, ciąg poświadczeń próbuje uwierzytelnić się przy użyciu pierwszego poświadczenia w sekwencji. Jeśli to poświadczenie nie może uzyskać tokenu dostępu, zostanie podjęta próba następnego poświadczenia w sekwencji itd., dopóki token dostępu nie zostanie pomyślnie uzyskany. Poniższy diagram sekwencji ilustruje to zachowanie:

Diagram ilustrujący przepływ uwierzytelniania łańcucha poświadczeń z sekwencyjnymi próbami w wielu poświadczeniach do momentu pomyślnego uzyskania tokenu.

Dlaczego warto używać łańcuchów poświadczeń

Poświadczenie łańcuchowe może oferować następujące korzyści:

Świadomość środowiska: automatycznie wybiera najbardziej odpowiednie poświadczenia na podstawie środowiska, w którym działa aplikacja. Bez niego musisz napisać kod podobny do następującego:

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

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

Bezproblemowe przejścia: Aplikacja może przejść z lokalnego programowania do środowiska przejściowego lub produkcyjnego bez zmiany kodu uwierzytelniania.
Ulepszona odporność: obejmuje mechanizm rezerwowy, który przechodzi do następnego poświadczenia, gdy poprzednia próba uzyskania tokenu dostępu zakończy się niepowodzeniem.

Jak wybrać poświadczenie łańcuchowe

Istnieją dwa różne podejścia do tworzenia łańcuchów poświadczeń:

"Rozerwanie" łańcucha: Zacznij od wstępnie skonfigurowanego łańcucha i wyklucz to, czego nie potrzebujesz. W przypadku tego podejścia zobacz sekcję Omówienie DefaultAzureCredential.
"Utwórz" łańcuch: zacznij od pustego łańcucha i uwzględnij tylko potrzebne elementy. Aby zapoznać się z tym podejściem, zobacz sekcję Omówienie ChainedTokenCredential.

Omówienie DefaultAzureCredential

DefaultAzureCredential jest ukierunkowanym na określone zastosowania, wstępnie skonfigurowanym łańcuchem poświadczeń. Jest ona przeznaczona do obsługi wielu środowisk wraz z najczęściej używanymi przepływami uwierzytelniania i narzędziami deweloperskich. W postaci graficznej podstawowy łańcuch wygląda następująco:

Kolejność, w której DefaultAzureCredential próbuje użyć danych uwierzytelniających, jest następująca.

Zamówienie	Poświadczenie	Opis	Włączone domyślnie?
1	środowiska	Odczytuje kolekcję zmiennych środowiskowych w celu określenia, czy dla aplikacji skonfigurowano głównego użytkownika usługi (użytkownika aplikacji). Jeśli tak, `DefaultAzureCredential` używa tych wartości do uwierzytelniania aplikacji na platformie Azure. Ta metoda jest najczęściej używana w środowiskach serwera, ale może być również używana podczas opracowywania lokalnie.	Tak
2	Tożsamość zasobów roboczych	Jeśli aplikacja zostanie wdrożona na hoście platformy Azure z włączoną tożsamością zadania, uwierzytelnij konto tej usługi.	Tak
3	tożsamość zarządzana	Jeśli aplikacja zostanie wdrożona na hoście platformy Azure z włączoną tożsamością zarządzaną, uwierzytelnij aplikację na platformie Azure przy użyciu tej tożsamości zarządzanej.	Tak
4	Visual Studio Code	Jeśli deweloper uwierzytelniony za pośrednictwem rozszerzenia zasobów platformy Azure programu Visual Studio Code i zostanie zainstalowany pakiet @azure/identity-vscode , uwierzytelnij to konto.	Tak
5	Interfejs wiersza polecenia platformy Azure	Jeśli deweloper uwierzytelnił się na platformie Azure za pomocą polecenia `az login` Azure CLI, uwierzytelnij aplikację na platformie Azure za pomocą tego samego konta.	Tak
6	Azure PowerShell	Jeśli deweloper uwierzytelnił się w Azure przy użyciu polecenia cmdlet `Connect-AzAccount` programu Azure PowerShell, uwierzytelnij aplikację w Azure przy użyciu tego samego konta.	Tak
7	interfejsu wiersza polecenia dewelopera platformy Azure	Jeśli deweloper zalogował się do platformy Azure za pomocą polecenia `azd auth login` narzędzia Azure Developer CLI, zaloguj się za pomocą tego samego konta.	Tak
8	Brokera	Uwierzytelnia się przy użyciu konta domyślnego zalogowanego do systemu operacyjnego za pośrednictwem brokera. Wymaga zainstalowania pakietu @azure/identity-broker .	Tak

W najprostszej formie można użyć bez parametrów wersji DefaultAzureCredential w następujący sposób:

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 dostosować DefaultAzureCredential

W poniższych sekcjach opisano strategie kontrolowania poświadczeń zawartych w łańcuchu.

Wyklucz kategorię typu poświadczeń

Aby wykluczyć wszystkie Developer tool lub Deployed service poświadczenia, ustaw odpowiednio zmienną środowiskową AZURE_TOKEN_CREDENTIALS na prod lub dev. Gdy jest używana wartość prod , podstawowy łańcuch poświadczeń wygląda następująco:

Diagram przedstawiający łańcuch DefaultAzureCredential z ustawionym AZURE_TOKEN_CREDENTIALS na

W przypadku użycia wartości dev łańcuch wygląda następująco:

Diagram przedstawiający łańcuch DefaultAzureCredential z AZURE_TOKEN_CREDENTIALS ustawionym na

Aby upewnić się, że zmienna środowiskowa jest zdefiniowana i ustawiona na obsługiwany ciąg, ustaw właściwość requiredEnvVars na AZURE_TOKEN_CREDENTIALS:

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

Używanie określonego poświadczenia

Aby wykluczyć wszystkie poświadczenia z wyjątkiem jednego, ustaw zmienną środowiskową AZURE_TOKEN_CREDENTIALS na nazwę poświadczenia. Możesz, na przykład, zmniejszyć DefaultAzureCredential do AzureCliCredential, ustawiając AZURE_TOKEN_CREDENTIALS na AzureCliCredential. Porównanie ciągów jest wykonywane w sposób niewrażliwy na wielkość liter. Prawidłowe wartości ciągów dla zmiennej środowiskowej obejmują:

AzureCliCredential
AzureDeveloperCliCredential
AzurePowerShellCredential
EnvironmentCredential
ManagedIdentityCredential
VisualStudioCodeCredential
WorkloadIdentityCredential

Ważne

Zmienna AZURE_TOKEN_CREDENTIALS środowiskowa obsługuje poszczególne nazwy poświadczeń w pakiecie w @azure/identity wersji 4.11.0 lub nowszej.

Aby upewnić się, że zmienna środowiskowa jest zdefiniowana i ustawiona na obsługiwany ciąg, ustaw właściwość requiredEnvVars na AZURE_TOKEN_CREDENTIALS:

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

ChainedTokenCredential — omówienie

ChainedTokenCredential to pusty łańcuch, do którego dodajesz poświadczenia zgodnie z potrzebami aplikacji. Przykład:

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

Przykładowy kod powyżej tworzy dostosowany łańcuch poświadczeń składający się z dwóch poświadczeń używanych podczas rozwoju. Najpierw podejmowana jest próba z AzureCliCredential, a w razie potrzeby z VisualStudioCodeCredential. W formie graficznej łańcuch wygląda następująco:

Diagram konfiguracji ChainedTokenCredential przedstawiający usługę AzureCliCredential jako podstawową metodę uwierzytelniania z programem VisualStudioCodeCredential jako opcją rezerwową pomocniczą.

Napiwek

Aby uzyskać lepszą wydajność, zoptymalizuj kolejność poświadczeń w ChainedTokenCredential z większości do najmniej używanych poświadczeń.

Instrukcja użytkowania DefaultAzureCredential

DefaultAzureCredential jest niewątpliwie najprostszym sposobem rozpoczęcia pracy z biblioteką tożsamości platformy Azure, ale ta wygoda wiąże się z pewnymi kompromisami. Po wdrożeniu aplikacji na platformie Azure należy zrozumieć wymagania dotyczące uwierzytelniania aplikacji. Z tego powodu zastąp DefaultAzureCredential określoną implementacją TokenCredential, taką jak ManagedIdentityCredential.

Oto dlaczego:

Problemy z debugowaniem: w przypadku niepowodzenia uwierzytelniania, debugowanie oraz identyfikacja wadliwych poświadczeń mogą być trudne. Należy włączyć rejestrowanie, aby zobaczyć postęp z jednego poświadczenia do następnego i stan powodzenia/niepowodzenia każdego z nich. Aby uzyskać więcej informacji, zobacz Debugowanie poświadczeń.
Obciążenie związane z wydajnością: proces sekwencyjnie próbujący uzyskać wiele poświadczeń może wprowadzić obciążenie związane z wydajnością. Na przykład tożsamość zarządzana jest niedostępna podczas uruchamiania na lokalnym komputerze deweloperskim. W związku z tym ManagedIdentityCredential zawsze kończy się niepowodzeniem w lokalnym środowisku projektowym.
Nieprzewidywalne zachowanie: DefaultAzureCredential sprawdza obecność określonych zmiennych środowiskowych. Możliwe, że ktoś może dodać lub zmodyfikować te zmienne środowiskowe na poziomie systemu na maszynie hosta. Te zmiany są stosowane globalnie i w związku z tym zmieniają zachowanie DefaultAzureCredential w czasie wykonywania w dowolnej aplikacji uruchomionej na tym komputerze.

Debugowanie poświadczeń

Aby zdiagnozować nieoczekiwany problem lub zrozumieć, co robi poświadczenie, włącz rejestrowanie w aplikacji. Przykład:

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.

W poprzednich danych wyjściowych zwróć uwagę, że DefaultAzureCredential pomyślnie nabył token przy użyciu polecenia AzureCliCredential.

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-10-10