Share via

@azure/identity package

  • Odwołanie

Klasy

AggregateAuthenticationError

Zawiera tablicę zawierającą errors wystąpienie authenticationError dla niepowodzeń uwierzytelniania z poświadczeń w obiekcie 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 Tożsamość Microsoft Entra przy użyciu kodu autoryzacji uzyskanego za pośrednictwem przepływu kodu autoryzacji opisanego bardziej szczegółowo w dokumentacji Tożsamość Microsoft Entra:

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 wygasa za pomocą polecenia interfejsu wiersza polecenia platformy Azure "az account get-access-token".
AzureDeveloperCliCredential

Azure Developer CLI 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 Tożsamość Microsoft Entra. Usługa AzureDeveloperCliCredential uwierzytelnia się w środowisku deweloperskim i uzyskuje token w imieniu zalogowanego użytkownika lub jednostki usługi w Azure Developer CLI. Działa on jako Azure Developer CLI zalogowany użytkownik lub jednostka usługi i wykonuje pod spodem polecenie interfejsu wiersza polecenia platformy Azure w celu uwierzytelnienia aplikacji w Tożsamość Microsoft Entra.

Konfigurowanie elementu AzureDeveloperCliCredential

Aby użyć tego poświadczenia, deweloper musi uwierzytelnić się lokalnie w Azure Developer CLI przy użyciu jednego z poniższych poleceń:

  1. Uruchom polecenie "azd auth login" w Azure Developer CLI, aby uwierzytelnić się interaktywnie jako użytkownik.
  2. Uruchom polecenie "azd auth login --client-id clientID --client-secret clientSecret --tenant-id tenant-tenant-tenantID", aby uwierzytelnić się jako jednostka usługi.

Może być konieczne powtórzenie tego procesu po określonym czasie, 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ę.
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 wygasa za pomocą polecenia Azure PowerShellGet-AzAccessToken -ResourceUrl {ResourceScope}
ChainedTokenCredential

Umożliwia wypróbowanie wielu TokenCredential implementacji do momentu, gdy jedna z metod getToken zwróci token dostępu.
ClientAssertionCredential

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

Umożliwia uwierzytelnianie Tożsamość Microsoft Entra 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/en-us/azure/active-directory/develop/active-directory-certificate-credentials#register-your-certificate-with-azure-ad
ClientSecretCredential

Umożliwia uwierzytelnianie Tożsamość Microsoft Entra przy użyciu klucza tajnego klienta, który został wygenerowany na potrzeby rejestracji aplikacji. Więcej informacji na temat konfigurowania klucza 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świadczenie wypróbowane w łańcuchowym poświadczeniu nie było dostępne do użycia jako poświadczenia. Zamiast traktować to jako błąd, który powinien zatrzymać łańcuch, zostaje złapany, a łańcuch kontynuuje
DefaultAzureCredential

Udostępnia domyślną konfigurację ChainedTokenCredential , która powinna działać w przypadku większości aplikacji korzystających z zestawu Azure SDK.
DeviceCodeCredential

Umożliwia uwierzytelnianie Tożsamość Microsoft Entra przy użyciu kodu urządzenia, który użytkownik może wprowadzić w programie https://microsoft.com/devicelogin.
EnvironmentCredential

Umożliwia uwierzytelnianie Tożsamość Microsoft Entra przy użyciu klucza tajnego klienta lub certyfikatu albo jako użytkownik z nazwą użytkownika i hasłem.
InteractiveBrowserCredential

Umożliwia uwierzytelnianie Tożsamość Microsoft Entra 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 App Service, aplikacjach 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/en-us/azure/active-directory/managed-identities-azure-resources/overview
OnBehalfOfCredential

Umożliwia uwierzytelnianie Tożsamość Microsoft Entra przy użyciu przepływu W imieniu.
UsernamePasswordCredential

Umożliwia uwierzytelnianie Tożsamość Microsoft Entra przy użyciu nazwy użytkownika i hasła 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

Nawiązuje połączenie z platformą Azure przy użyciu poświadczeń dostarczonych przez rozszerzenie VSCode "Konto platformy Azure". Gdy użytkownik zaloguje się za pośrednictwem rozszerzenia, to poświadczenie może współużytkować ten sam token odświeżania, który jest buforowany przez rozszerzenie.

Znany problem polega na tym, że to poświadczenie nie działa z wersjami rozszerzenia konta platformy Azure nowszymi niż 0.9.11. Długoterminowe rozwiązanie tego problemu jest w toku. W międzyczasie rozważ uwierzytelnianie w usłudze AzureCliCredential.
WorkloadIdentityCredential

Uwierzytelnianie tożsamości obciążenia to funkcja platformy 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, zamiast korzystać z 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 (SAC), 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 obracania ich. 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 Tożsamość obciążeń Microsoft Entra 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 Tożsamość obciążeń 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

Parametry opcjonalne do błędu AuthenticationRequiredError
AuthorityValidationOptions

Udostępnia opcje konfigurowania sposobu weryfikacji urzędu przez bibliotekę tożsamości podczas żądań uwierzytelniania w celu Tożsamość Microsoft Entra.
AuthorizationCodeCredentialOptions

Opcje dla obiektu AuthorizationCodeCredential
AzureCliCredentialOptions

Opcje dla obiektu AzureCliCredential
AzureDeveloperCliCredentialOptions

Opcje dla elementu AzureDeveloperCliCredential
AzurePowerShellCredentialOptions

Opcje dla obiektu 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 na potrzeby dostosowywania przeglądarki
ClientAssertionCredentialOptions

Opcje obiektu ClientAssertionCredential
ClientCertificateCredentialOptions

Parametry opcjonalne dla klasy ClientCertificateCredential .
ClientCertificatePEMCertificate

Wymagane opcje konfiguracji dla elementu ClientCertificateCredential z zawartością ciągu certyfikatu PEM
ClientCertificatePEMCertificatePath

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

Parametry opcjonalne dla klasy ClientSecretCredential .
CredentialPersistenceOptions

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

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

Udostępnia opcje konfigurowania klasy DefaultAzureCredential .
DefaultAzureCredentialResourceIdOptions

Udostępnia opcje konfigurowania klasy DefaultAzureCredential . Ta odmiana obsługuje elementy managedIdentityResourceId , a nie managedIdentityClientId, ponieważ obsługiwany jest tylko jeden z obu.
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 do wyświetlenia użytkownikowi, który zawiera instrukcję zawierającą te szczegóły.
EnvironmentCredentialOptions

Umożliwia uwierzytelnianie Tożsamość Microsoft Entra 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/en-us/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 tokenuCredential.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 z użytkownikiem.
ManagedIdentityCredentialClientIdOptions

Opcje wysyłania w konstruktorze ManagedIdentityCredential . Ta odmiana obsługuje elementy clientId , a nie resourceId, ponieważ obsługiwany jest tylko jeden z obu.
ManagedIdentityCredentialResourceIdOptions

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

Opcje dla aplikacji wielodostępnych, które umożliwiają korzystanie z dodatkowych dozwolonych dzierżaw.
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 umożliwiające podanie tokenu uwierzytelniania.
TokenCredentialOptions

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

Definiuje opcje dla klasy UsernamePasswordCredential .
VisualStudioCodeCredentialOptions

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

Opcje dla obciążeniaIdentityCredential

Aliasy typu

BrokerOptions

Parametry umożliwiające uwierzytelnianie brokera WAM w obiekcie InteractiveBrowserCredential.
BrowserLoginStyle

(Funkcja tylko w przeglądarce) "Styl logowania", który ma być używany w przepływie uwierzytelniania:

  • "przekierowanie" przekierowuje użytkownika do strony uwierzytelniania, a następnie przekierowuje ich z powrotem do strony po zakończeniu uwierzytelniania.
  • W oknie podręcznym zostanie otwarte nowe okno przeglądarki z zainicjowanym przepływem przekierowania. Istniejące okno przeglądarki użytkownika nie pozostawia bieżącej strony
ClientCertificateCredentialPEMConfiguration

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

Definiuje podpis wywołania zwrotnego, który zostanie przekazany do obiektu DeviceCodeCredential w celu wyświetlenia szczegółów uwierzytelniania użytkownikowi.
IdentityPlugin

Typ wtyczki tożsamości platformy Azure, funkcja akceptująca kontekst wtyczki.
OnBehalfOfCredentialOptions

Parametry opcjonalne dla 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"
  • "clientId"
  • "tenantId"
  • "nazwa użytkownika"
  • "version"

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

Obecnie jedyną dostępną wersją jest: "1.0", która jest zawsze ustawiana, gdy rekord uwierzytelniania jest serializowany.
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 } from "@azure/identity";

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 obiektu DefaultAzureCredential.
serializeAuthenticationRecord(AuthenticationRecord)

Serializuje element AuthenticationRecord w ciągu.

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

  • "urząd"
  • "homeAccountId"
  • "clientId"
  • "tenantId"
  • "nazwa użytkownika"
  • "version"

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: udostępnia zależności VisualStudioCodeCredential i włącza je

Przykład:

import { cachePersistencePlugin } from "@azure/identity-cache-persistence";

import { useIdentityPlugin, DefaultAzureCredential } from "@azure/identity";
useIdentityPlugin(cachePersistencePlugin);

// The plugin has the capability to extend `DefaultAzureCredential` and to
// add middleware to the underlying credentials, such as persistence.
const credential = new DefaultAzureCredential({
  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"
  • "clientId"
  • "tenantId"
  • "nazwa użytkownika"
  • "version"

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

Obecnie jedyną dostępną wersją jest: "1.0", która jest zawsze ustawiana, gdy rekord uwierzytelniania jest serializowany.

function deserializeAuthenticationRecord(serializedRecord: string): AuthenticationRecord

Parametry

serializedRecord

string

Rekord uwierzytelniania wcześniej serializowany na 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 } from "@azure/identity";

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świadczenia 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 obiektu DefaultAzureCredential.

function getDefaultAzureCredential(): TokenCredential

Zwraca

TokenCredential

serializeAuthenticationRecord(AuthenticationRecord)

Serializuje element AuthenticationRecord w ciągu.

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

  • "urząd"
  • "homeAccountId"
  • "clientId"
  • "tenantId"
  • "nazwa użytkownika"
  • "version"

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: udostępnia zależności VisualStudioCodeCredential i włącza je

Przykład:

import { cachePersistencePlugin } from "@azure/identity-cache-persistence";

import { useIdentityPlugin, DefaultAzureCredential } from "@azure/identity";
useIdentityPlugin(cachePersistencePlugin);

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

function useIdentityPlugin(plugin: IdentityPlugin)

Parametry

plugin
IdentityPlugin

wtyczka do zarejestrowania