Udostępnij za pomocą

@azure/identity package

Klasy

AggregateAuthenticationError

Udostępnia tablicę errors zawierającą wystąpienie AuthenticationError dla błędów uwierzytelniania z poświadczeń w ChainedTokenCredential.
AuthenticationError

Zawiera szczegółowe informacje o niepowodzeniu uwierzytelniania w usłudze Azure Active Directory. Pole errorResponse zawiera więcej szczegółów na temat konkretnego błędu.
AuthenticationRequiredError

Błąd używany do wymuszania uwierzytelniania po próbie dyskretnego pobrania tokenu.
AuthorizationCodeCredential

Umożliwia uwierzytelnianie w usłudze Microsoft Entra ID przy użyciu kodu autoryzacji uzyskanego za pośrednictwem przepływu kodu autoryzacji, opisanego bardziej szczegółowo w dokumentacji identyfikatora entra firmy Microsoft:

https://learn.microsoft.com/entra/identity-platform/v2-oauth2-auth-code-flow
AzureCliCredential

To poświadczenie będzie używać aktualnie zalogowanych informacji logowania użytkownika za pośrednictwem narzędzia wiersza polecenia platformy Azure ('az'). W tym celu odczytuje token dostępu użytkownika i wygaśnie czas za pomocą polecenia interfejsu wiersza polecenia platformy Azure "az account get-access-token".
AzureDeveloperCliCredential

Interfejs wiersza polecenia dla deweloperów platformy Azure to narzędzie interfejsu wiersza polecenia, które umożliwia deweloperom tworzenie i wdrażanie zasobów na platformie Azure oraz zarządzanie nimi. Jest ona oparta na interfejsie wiersza polecenia platformy Azure i udostępnia dodatkowe funkcje specyficzne dla deweloperów platformy Azure. Umożliwia ona użytkownikom uwierzytelnianie się jako użytkownik i/lub jednostka usługi względem identyfikatora Entra firmy Microsoft. Usługa AzureDeveloperCliCredential uwierzytelnia się w środowisku dewelopera i uzyskuje token w imieniu zalogowanego użytkownika lub jednostki usługi w interfejsie wiersza polecenia dewelopera platformy Azure. Działa jako interfejs wiersza polecenia dewelopera platformy Azure zalogowany w użytkowniku lub jednostce usługi i wykonuje polecenie interfejsu wiersza polecenia platformy Azure poniżej, aby uwierzytelnić aplikację pod identyfikatorem Entra firmy Microsoft.

Konfigurowanie elementu AzureDeveloperCliCredential

Aby użyć tego poświadczenia, deweloper musi uwierzytelnić się lokalnie w interfejsie wiersza polecenia dewelopera platformy Azure przy użyciu jednego z poniższych poleceń:

  1. Uruchom polecenie "azd auth login" w interfejsie wiersza polecenia dla deweloperów platformy Azure, aby uwierzytelnić się interaktywnie jako użytkownik.
  2. Uruchom polecenie "azd auth login --client-id clientID --client-secret clientSecret --tenant-id tenant-tenantID", aby uwierzytelnić się jako jednostka usługi.

Może być konieczne powtórzenie tego procesu po upływie określonego czasu, w zależności od ważności tokenu odświeżania w organizacji. Zazwyczaj okres ważności tokenu odświeżania wynosi od kilku tygodni do kilku miesięcy. Polecenie AzureDeveloperCliCredential wyświetli monit o ponowne zalogowanie się.
AzurePipelinesCredential

To poświadczenie jest przeznaczone do użycia w usłudze Azure Pipelines z połączeniami usług jako konfiguracją federacji tożsamości obciążenia.
AzurePowerShellCredential

To poświadczenie będzie używać aktualnie zalogowanych informacji o użytkowniku z modułu Azure PowerShell. W tym celu odczytuje token dostępu użytkownika i wygaśnie czas za pomocą polecenia programu Azure PowerShell Get-AzAccessToken -ResourceUrl {ResourceScope}
ChainedTokenCredential

Umożliwia wypróbowanie wielu implementacji TokenCredential, dopóki jedna z metod getToken nie zwróci tokenu dostępu. Aby uzyskać więcej informacji, zobacz ChainedTokenCredential overview.
ClientAssertionCredential

Uwierzytelnia jednostkę usługi przy użyciu asercji JWT.
ClientCertificateCredential

Umożliwia uwierzytelnianie w usłudze Microsoft Entra ID przy użyciu certyfikatu zakodowanego za pomocą protokołu PEM przypisanego do rejestracji aplikacji. Więcej informacji na temat konfigurowania uwierzytelniania certyfikatów można znaleźć tutaj:

https://learn.microsoft.com/azure/active-directory/develop/active-directory-certificate-credentials#register-your-certificate-with-azure-ad
ClientSecretCredential

Umożliwia uwierzytelnianie w identyfikatorze Entra firmy Microsoft przy użyciu klucza tajnego klienta wygenerowanego na potrzeby rejestracji aplikacji. Więcej informacji na temat konfigurowania wpisu tajnego klienta można znaleźć tutaj:

https://learn.microsoft.com/entra/identity-platform/quickstart-configure-app-access-web-apis#add-credentials-to-your-web-application
CredentialUnavailableError

Oznacza to, że poświadczenia, które zostały wypróbowane w łańcuchowym poświadczeniu, nie były dostępne do użycia jako poświadczenia. Zamiast traktować to jako błąd, który powinien zatrzymać łańcuch, jest złapany, a łańcuch kontynuuje
DefaultAzureCredential

Udostępnia domyślną konfigurację ChainedTokenCredential, która działa w przypadku większości aplikacji korzystających z bibliotek klienckich zestawu Azure SDK. Aby uzyskać więcej informacji, zobacz Omówienie domyślneAzureCredential.

Następujące typy poświadczeń zostaną wypróbowane w następującej kolejności:

Zapoznaj się z dokumentacją tych typów poświadczeń, aby uzyskać więcej informacji na temat sposobu próby uwierzytelnienia.

W poniższym przykładzie pokazano, jak używać tej requiredEnvVars opcji, aby upewnić się, że pewne zmienne środowiskowe są ustawiane przed utworzeniem wystąpienia DefaultAzureCredential . Jeśli brakuje którejkolwiek z określonych zmiennych środowiskowych lub jest ona pusta, zostanie zgłoszony błąd, który uniemożliwi aplikacji kontynuowanie wykonywania bez niezbędnej konfiguracji. Pokazano również, jak ustawić zmienną środowiskową AZURE_TOKEN_CREDENTIALS w celu kontrolowania, które poświadczenia są uwzględniane w łańcuchu.

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

const credential = new DefaultAzureCredential({
  requiredEnvVars: [
    "AZURE_CLIENT_ID",
    "AZURE_TENANT_ID",
    "AZURE_CLIENT_SECRET",
    "AZURE_TOKEN_CREDENTIALS",
  ],
});
DeviceCodeCredential

Umożliwia uwierzytelnianie w usłudze Microsoft Entra ID przy użyciu kodu urządzenia, który użytkownik może wprowadzić w https://microsoft.com/devicelogin.
EnvironmentCredential

Umożliwia uwierzytelnianie do identyfikatora Microsoft Entra przy użyciu klucza tajnego klienta lub certyfikatu.
InteractiveBrowserCredential

Umożliwia uwierzytelnianie w usłudze Microsoft Entra ID wewnątrz przeglądarki internetowej przy użyciu interaktywnego przepływu logowania.
ManagedIdentityCredential

Podejmuje próbę uwierzytelnienia przy użyciu tożsamości zarządzanej dostępnej w środowisku wdrażania. Ten typ uwierzytelniania działa na maszynach wirtualnych platformy Azure, wystąpieniach usługi App Service, aplikacjach usługi Azure Functions, usługach Azure Kubernetes Services, wystąpieniach usługi Azure Service Fabric i w usłudze Azure Cloud Shell.

Więcej informacji na temat konfigurowania tożsamości zarządzanych można znaleźć tutaj: https://learn.microsoft.com/azure/active-directory/managed-identities-azure-resources/overview
OnBehalfOfCredential

Włącza uwierzytelnianie do identyfikatora Entra firmy Microsoft przy użyciu w imieniu przepływu.
UsernamePasswordCredential

Umożliwia uwierzytelnianie w usłudze Microsoft Entra ID z nazwą użytkownika i hasłem użytkownika. To poświadczenie wymaga wysokiego stopnia zaufania, dlatego należy używać go tylko wtedy, gdy nie można używać innych, bezpieczniejszych typów poświadczeń.
VisualStudioCodeCredential

Łączy się z platformą Azure przy użyciu konta użytkownika zalogowanego za pośrednictwem rozszerzenia Azure Resources w Visual Studio Code. Po zalogowaniu się użytkownika za pośrednictwem rozszerzenia to poświadczenie może współużytkować ten sam token odświeżania, który jest buforowany przez rozszerzenie.
WorkloadIdentityCredential

Uwierzytelnianie tożsamości obciążenia to funkcja na platformie Azure, która umożliwia aplikacjom działającym na maszynach wirtualnych dostęp do innych zasobów platformy Azure bez konieczności używania jednostki usługi lub tożsamości zarządzanej. W przypadku uwierzytelniania tożsamości obciążenia aplikacje uwierzytelniają się przy użyciu własnej tożsamości, a nie przy użyciu jednostki usługi udostępnionej lub tożsamości zarządzanej. Uwierzytelnianie tożsamości obciążenia korzysta z koncepcji poświadczeń konta usługi (SACs), które są automatycznie tworzone przez platformę Azure i przechowywane bezpiecznie na maszynie wirtualnej. Korzystając z uwierzytelniania tożsamości obciążenia, można uniknąć konieczności zarządzania jednostkami usługi lub tożsamościami zarządzanymi dla każdej aplikacji na każdej maszynie wirtualnej i obracać je. Ponadto, ponieważ kontrolery Zabezpieczeń są tworzone automatycznie i zarządzane przez platformę Azure, nie musisz martwić się o przechowywanie i zabezpieczanie poufnych poświadczeń. Element WorkloadIdentityCredential obsługuje uwierzytelnianie identyfikatora obciążenia firmy Microsoft w usłudze Azure Kubernetes i uzyskuje token przy użyciu kontrolerów Zabezpieczeń dostępnych w środowisku usługi Azure Kubernetes. Aby uzyskać więcej informacji, zobacz identyfikator obciążenia firmy Microsoft Entra.

Interfejsy

AccessToken

Reprezentuje token dostępu z czasem wygaśnięcia.
AuthenticationRecord

Rekord używany do znajdowania buforowanych tokenów w pamięci podręcznej.
AuthenticationRequiredErrorOptions

Opcjonalne parametry AuthenticationRequiredError
AuthorityValidationOptions

Udostępnia opcje konfigurowania sposobu sprawdzania poprawności urzędu przez bibliotekę tożsamości podczas żądań uwierzytelniania do identyfikatora Entra firmy Microsoft.
AuthorizationCodeCredentialOptions

Opcje AuthorizationCodeCredential
AzureCliCredentialOptions

Opcje AzureCliCredential
AzureDeveloperCliCredentialOptions

Opcje azureDeveloperCliCredential
AzurePipelinesCredentialOptions

Opcjonalne parametry dla klasy AzurePipelinesCredential.
AzurePowerShellCredentialOptions

Opcje AzurePowerShellCredential
BrokerAuthOptions

Opcje konfiguracji interactiveBrowserCredential do obsługi uwierzytelniania brokera WAM.
BrokerDisabledOptions

Parametry, gdy uwierzytelnianie brokera WAM jest wyłączone.
BrokerEnabledOptions

Parametry po włączeniu uwierzytelniania brokera WAM.
BrowserCustomizationOptions

Opcje konfiguracji udostępnionej dla dostosowywania przeglądarki
ClientAssertionCredentialOptions

Opcje ClientAssertionCredential
ClientCertificateCredentialOptions

Opcjonalne parametry klasy ClientCertificateCredential.
ClientCertificatePEMCertificate

Wymagane opcje konfiguracji dla ClientCertificateCredentialz zawartością ciągu certyfikatu PEM
ClientCertificatePEMCertificatePath

Wymagane opcje konfiguracji dla ClientCertificateCredential, ze ścieżką do certyfikatu PEM.
ClientSecretCredentialOptions

Opcjonalne parametry klasy ClientSecretCredential.
CredentialPersistenceOptions

Udostępnione opcje konfiguracji dla poświadczeń, które obsługują trwałe buforowanie tokenów.
DefaultAzureCredentialClientIdOptions

Udostępnia opcje konfigurowania klasy DefaultAzureCredential. Ta odmiana obsługuje managedIdentityClientId, a nie managedIdentityResourceId, ponieważ obsługiwana jest tylko jedna z obu opcji.
DefaultAzureCredentialOptions

Udostępnia opcje konfigurowania klasy DefaultAzureCredential.
DefaultAzureCredentialResourceIdOptions

Udostępnia opcje konfigurowania klasy DefaultAzureCredential. Ta odmiana obsługuje managedIdentityResourceId, a nie managedIdentityClientId, ponieważ obsługiwana jest tylko jedna z obu opcji.
DeviceCodeCredentialOptions

Definiuje opcje dla klasy InteractiveBrowserCredential dla Node.js.
DeviceCodeInfo

Udostępnia kod użytkownika i identyfikator URI weryfikacji, w którym należy wprowadzić kod. Zawiera również komunikat wyświetlany użytkownikowi, który zawiera instrukcję zawierającą te szczegóły.
EnvironmentCredentialOptions

Włącza uwierzytelnianie do identyfikatora Entra firmy Microsoft w zależności od dostępnych zmiennych środowiskowych. Definiuje opcje dla klasy EnvironmentCredential.
ErrorResponse

Aby uzyskać więcej informacji, zobacz oficjalną dokumentację:

https://learn.microsoft.com/azure/active-directory/develop/v1-protocols-oauth-code#error-response-1

UWAGA: Ta dokumentacja dotyczy obsługi protokołu OAuth w wersji 1, ale te same szczegóły odpowiedzi na błędy nadal dotyczą wersji 2.
GetBearerTokenProviderOptions

Opcje konfigurowania dostawcy tokenów.
GetTokenOptions

Definiuje opcje tokenCredential.getToken.
InteractiveBrowserCredentialInBrowserOptions

Definiuje typowe opcje dla klasy InteractiveBrowserCredential.
InteractiveBrowserCredentialNodeOptions

Definiuje typowe opcje dla klasy InteractiveBrowserCredential.
InteractiveCredentialOptions

Typowe opcje konstruktora dla poświadczeń tożsamości, które wymagają interakcji użytkownika.
ManagedIdentityCredentialClientIdOptions

Opcje wysyłania w konstruktorze ManagedIdentityCredential. Ta odmiana obsługuje clientId, a nie resourceId, ponieważ obsługiwana jest tylko jedna z obu opcji.
ManagedIdentityCredentialObjectIdOptions

Opcje wysyłania w konstruktorze ManagedIdentityCredential. Ta odmiana obsługuje objectId jako argument konstruktora.
ManagedIdentityCredentialResourceIdOptions

Opcje wysyłania w konstruktorze ManagedIdentityCredential. Ta odmiana obsługuje resourceId, a nie clientId, ponieważ obsługiwana jest tylko jedna z obu opcji.
MultiTenantTokenCredentialOptions

Opcje dla aplikacji wielodostępnych, które umożliwiają korzystanie z dodatkowych dozwolonych dzierżaw.
OnBehalfOfCredentialAssertionOptions

Definiuje parametry do uwierzytelniania OnBehalfOfCredential z asercją.
OnBehalfOfCredentialCertificateOptions

Definiuje parametry do uwierzytelniania OnBehalfOfCredential przy użyciu certyfikatu.
OnBehalfOfCredentialSecretOptions

Definiuje parametry do uwierzytelniania OnBehalfOfCredential za pomocą wpisu tajnego.
TokenCachePersistenceOptions

Parametry, które umożliwiają trwałość pamięci podręcznej tokenu w poświadczeniach tożsamości.
TokenCredential

Reprezentuje poświadczenie, które może zapewnić token uwierzytelniania.
TokenCredentialOptions

Udostępnia opcje konfigurowania sposobu, w jaki biblioteka tożsamości wysyła żądania uwierzytelniania do identyfikatora Entra firmy Microsoft.
UsernamePasswordCredentialOptions

Definiuje opcje dla klasy UsernamePasswordCredential.
VisualStudioCodeCredentialOptions

Udostępnia opcje konfigurowania poświadczeń programu Visual Studio Code.
WorkloadIdentityCredentialOptions

Opcje WorkloadIdentityCredential

Aliasy typu

BrokerOptions

Parametry, które umożliwiają uwierzytelnianie brokera WAM w InteractiveBrowserCredential.
BrowserLoginStyle

(Funkcja tylko w przeglądarce) Styl logowania do użycia w przepływie uwierzytelniania:

  • "przekierowanie" przekierowuje użytkownika do strony uwierzytelniania, a następnie przekierowuje ich z powrotem do strony po zakończeniu uwierzytelniania.
  • Okno podręczne otwiera nowe okno przeglądarki za pomocą przepływu przekierowania jest inicjowane. Istniejące okno przeglądarki użytkownika nie pozostawia bieżącej strony
ClientCertificateCredentialPEMConfiguration

Wymagane opcje konfiguracji dla ClientCertificateCredential, z zawartością ciągu certyfikatu PEM lub ścieżką do certyfikatu PEM.
DefaultAzureCredentialEnvVars

Często obsługiwane zmienne środowiskowe dla klasy DefaultAzureCredential .
DeviceCodePromptCallback

Definiuje podpis wywołania zwrotnego, który zostanie przekazany do elementu DeviceCodeCredential na potrzeby wyświetlania szczegółów uwierzytelniania użytkownikowi.
IdentityPlugin

Typ wtyczki azure Identity, funkcja akceptująca kontekst wtyczki.
OnBehalfOfCredentialOptions

Opcjonalne parametry klasy OnBehalfOfCredential.

Wyliczenia

AzureAuthorityHosts

Lista znanych hostów urzędu platformy Azure

Funkcje

deserializeAuthenticationRecord(string)

Deserializuje wcześniej serializowany rekord uwierzytelniania z ciągu do obiektu.

Ciąg wejściowy musi zawierać następujące właściwości:

  • "urząd"
  • "homeAccountId" (identyfikator konta domowego)
  • "clientId" (identyfikator klienta)
  • "tenantId" (identyfikator dzierżawy)
  • "nazwa użytkownika"
  • "wersja"

Jeśli otrzymana wersja nie jest obsługiwana, zostanie zgłoszony błąd.

W tej chwili jedyną dostępną wersją jest: "1.0", która jest zawsze ustawiana po serializacji rekordu uwierzytelniania.
getBearerTokenProvider(TokenCredential, string | string[], GetBearerTokenProviderOptions)

Zwraca wywołanie zwrotne, które zapewnia token elementu nośnego. Na przykład token elementu nośnego może służyć do uwierzytelniania żądania w następujący sposób:

import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";
import { createPipelineRequest } from "@azure/core-rest-pipeline";

const credential = new DefaultAzureCredential();
const scope = "https://cognitiveservices.azure.com/.default";
const getAccessToken = getBearerTokenProvider(credential, scope);
const token = await getAccessToken();

// usage
const request = createPipelineRequest({ url: "https://example.com" });
request.headers.set("Authorization", `Bearer ${token}`);
getDefaultAzureCredential()

Zwraca nowe wystąpienie DefaultAzureCredential.
serializeAuthenticationRecord(AuthenticationRecord)

Serializuje AuthenticationRecord w ciągu.

Dane wyjściowe zserializowanego rekordu uwierzytelniania będą zawierać następujące właściwości:

  • "urząd"
  • "homeAccountId" (identyfikator konta domowego)
  • "clientId" (identyfikator klienta)
  • "tenantId" (identyfikator dzierżawy)
  • "nazwa użytkownika"
  • "wersja"

Aby później przekonwertować ten ciąg na serializowany AuthenticationRecord, użyj wyeksportowanej funkcji deserializeAuthenticationRecord().
useIdentityPlugin(IdentityPlugin)

Rozszerzanie tożsamości platformy Azure o dodatkowe funkcje. Przekaż wtyczkę z pakietu wtyczki, na przykład:

  • @azure/identity-cache-persistence: zapewnia trwałe buforowanie tokenów
  • @azure/identity-vscode: zapewnia zależności VisualStudioCodeCredential i włącza je

Przykład:

import { useIdentityPlugin, DeviceCodeCredential } from "@azure/identity";

useIdentityPlugin(cachePersistencePlugin);
// The plugin has the capability to extend `DeviceCodeCredential` and to
// add middleware to the underlying credentials, such as persistence.
const credential = new DeviceCodeCredential({
  tokenCachePersistenceOptions: {
    enabled: true,
  },
});

Szczegóły funkcji

deserializeAuthenticationRecord(string)

Deserializuje wcześniej serializowany rekord uwierzytelniania z ciągu do obiektu.

Ciąg wejściowy musi zawierać następujące właściwości:

  • "urząd"
  • "homeAccountId" (identyfikator konta domowego)
  • "clientId" (identyfikator klienta)
  • "tenantId" (identyfikator dzierżawy)
  • "nazwa użytkownika"
  • "wersja"

Jeśli otrzymana wersja nie jest obsługiwana, zostanie zgłoszony błąd.

W tej chwili jedyną dostępną wersją jest: "1.0", która jest zawsze ustawiana po serializacji rekordu uwierzytelniania.

function deserializeAuthenticationRecord(serializedRecord: string): AuthenticationRecord

Parametry

serializedRecord

string

Rekord uwierzytelniania wcześniej serializowany w ciąg.

Zwraca

AuthenticationRecord

UwierzytelnianieRekord.

getBearerTokenProvider(TokenCredential, string | string[], GetBearerTokenProviderOptions)

Zwraca wywołanie zwrotne, które zapewnia token elementu nośnego. Na przykład token elementu nośnego może służyć do uwierzytelniania żądania w następujący sposób:

import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";
import { createPipelineRequest } from "@azure/core-rest-pipeline";

const credential = new DefaultAzureCredential();
const scope = "https://cognitiveservices.azure.com/.default";
const getAccessToken = getBearerTokenProvider(credential, scope);
const token = await getAccessToken();

// usage
const request = createPipelineRequest({ url: "https://example.com" });
request.headers.set("Authorization", `Bearer ${token}`);

function getBearerTokenProvider(credential: TokenCredential, scopes: string | string[], options?: GetBearerTokenProviderOptions): () => Promise<string>

Parametry

credential
TokenCredential

Poświadczenie używane do uwierzytelniania żądania.

scopes

string | string[]

Zakresy wymagane dla tokenu elementu nośnego.

options
GetBearerTokenProviderOptions

Opcje konfigurowania dostawcy tokenów.

Zwraca

() => Promise<string>

wywołanie zwrotne, które zapewnia token elementu nośnego.

getDefaultAzureCredential()

Zwraca nowe wystąpienie DefaultAzureCredential.

function getDefaultAzureCredential(): TokenCredential

Zwraca

TokenCredential

serializeAuthenticationRecord(AuthenticationRecord)

Serializuje AuthenticationRecord w ciągu.

Dane wyjściowe zserializowanego rekordu uwierzytelniania będą zawierać następujące właściwości:

  • "urząd"
  • "homeAccountId" (identyfikator konta domowego)
  • "clientId" (identyfikator klienta)
  • "tenantId" (identyfikator dzierżawy)
  • "nazwa użytkownika"
  • "wersja"

Aby później przekonwertować ten ciąg na serializowany AuthenticationRecord, użyj wyeksportowanej funkcji deserializeAuthenticationRecord().

function serializeAuthenticationRecord(record: AuthenticationRecord): string

Parametry

record
AuthenticationRecord

Zwraca

string

useIdentityPlugin(IdentityPlugin)

Rozszerzanie tożsamości platformy Azure o dodatkowe funkcje. Przekaż wtyczkę z pakietu wtyczki, na przykład:

  • @azure/identity-cache-persistence: zapewnia trwałe buforowanie tokenów
  • @azure/identity-vscode: zapewnia zależności VisualStudioCodeCredential i włącza je

Przykład:

import { useIdentityPlugin, DeviceCodeCredential } from "@azure/identity";

useIdentityPlugin(cachePersistencePlugin);
// The plugin has the capability to extend `DeviceCodeCredential` and to
// add middleware to the underlying credentials, such as persistence.
const credential = new DeviceCodeCredential({
  tokenCachePersistenceOptions: {
    enabled: true,
  },
});

function useIdentityPlugin(plugin: IdentityPlugin)

Parametry

plugin
IdentityPlugin

wtyczka do zarejestrowania