@azure/identity package

  • Riferimento

Classi

AggregateAuthenticationError

Fornisce una errors matrice contenente l'istanza di AuthenticationError per gli errori di autenticazione dalle credenziali in un oggetto ChainedTokenCredential.
AuthenticationError

Fornisce informazioni dettagliate su un errore di autenticazione con Azure Active Directory. Il errorResponse campo contiene altri dettagli sull'errore specifico.
AuthenticationRequiredError

Errore usato per applicare l'autenticazione dopo aver tentato di recuperare un token in modo invisibile all'utente.
AuthorizationCodeCredential

Consente all'autenticazione di Microsoft Entra ID l'uso di un codice di autorizzazione ottenuto tramite il flusso del codice di autorizzazione, descritto in dettaglio nella documentazione di Microsoft Entra ID:

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

Questa credenziale userà le informazioni di accesso utente attualmente registrate tramite lo strumento della riga di comando dell'interfaccia della riga di comando di Azure ('az'). A tale scopo, leggerà il token di accesso utente e la scadenza con il comando dell'interfaccia della riga di comando di Azure "az account get-access-token".
AzureDeveloperCliCredential

Azure Developer CLI è uno strumento di interfaccia della riga di comando che consente agli sviluppatori di creare, gestire e distribuire risorse in Azure. Si basa sull'interfaccia della riga di comando di Azure e offre funzionalità aggiuntive specifiche per gli sviluppatori di Azure. Consente agli utenti di eseguire l'autenticazione come utente e/o un'entità servizio rispetto a Microsoft Entra ID. AzureDeveloperCliCredential esegue l'autenticazione in un ambiente di sviluppo e acquisisce un token per conto dell'utente o dell'entità servizio connessi nell'Azure Developer CLI. Funge da Azure Developer CLI connesso all'utente o all'entità servizio ed esegue un comando dell'interfaccia della riga di comando di Azure sotto per autenticare l'applicazione in base alla Microsoft Entra ID.

Configurare AzureDeveloperCliCredential

Per usare questa credenziale, lo sviluppatore deve eseguire l'autenticazione in locale in Azure Developer CLI usando uno dei comandi seguenti:

  1. Eseguire "azd auth login" in Azure Developer CLI per autenticare in modo interattivo come utente.
  2. Eseguire "azd auth login --client-id client-id --client-secret clientSecret --tenant-id tenantID" per eseguire l'autenticazione come entità servizio.

Potrebbe essere necessario ripetere questo processo dopo un determinato periodo di tempo, a seconda della validità del token di aggiornamento nell'organizzazione. In genere, il periodo di validità del token di aggiornamento è di qualche settimana a pochi mesi. AzureDeveloperCliCredential richiederà di nuovo di accedere.
AzurePowerShellCredential

Questa credenziale userà le informazioni utente attualmente registrate dal modulo Azure PowerShell. A tale scopo, leggerà il token di accesso utente e la scadenza con il comando Azure PowerShellGet-AzAccessToken -ResourceUrl {ResourceScope}
ChainedTokenCredential

Consente di provare più TokenCredential implementazioni fino a quando uno dei metodi getToken restituisce un token di accesso.
ClientAssertionCredential

Autentica un'entità servizio con un'asserzione JWT.
ClientCertificateCredential

Consente l'autenticazione per Microsoft Entra ID usando un certificato con codifica PEM assegnato a una registrazione app. Altre informazioni su come configurare l'autenticazione del certificato sono disponibili qui:

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

Consente l'autenticazione per Microsoft Entra ID usando un segreto client generato per una registrazione dell'app. Altre informazioni su come configurare un segreto client sono disponibili qui:

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

Ciò indica che le credenziali che sono state tentate in una credenziale concatenata non erano disponibili per essere usate come credenziali. Invece di considerare questo come un errore che dovrebbe arrestare la catena, viene catturato e la catena continua
DefaultAzureCredential

Fornisce una configurazione predefinita chainedTokenCredential che deve funzionare per la maggior parte delle applicazioni che usano Azure SDK.
DeviceCodeCredential

Consente l'autenticazione per Microsoft Entra ID usando un codice del dispositivo che l'utente può immettere in https://microsoft.com/devicelogin.
EnvironmentCredential

Consente l'autenticazione per Microsoft Entra ID usando un segreto client o un certificato oppure come utente con nome utente e password.
InteractiveBrowserCredential

Consente l'autenticazione per Microsoft Entra ID all'interno del Web browser usando il flusso di accesso interattivo.
ManagedIdentityCredential

Tenta di eseguire l'autenticazione usando un'identità gestita disponibile nell'ambiente di distribuzione. Questo tipo di autenticazione funziona in macchine virtuali di Azure, istanze di servizio app, applicazioni Funzioni di Azure, servizi Azure Kubernetes, istanze di Azure Service Fabric e all'interno del Cloud Shell di Azure.

Altre informazioni sulla configurazione delle identità gestite sono disponibili qui: https://learn.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/overview
OnBehalfOfCredential

Consente l'autenticazione per Microsoft Entra ID usando il flusso On Behalf Of.
UsernamePasswordCredential

Consente l'autenticazione per Microsoft Entra ID con nome utente e password di un utente. Questa credenziale richiede un livello elevato di attendibilità, pertanto è consigliabile usarla solo quando non è possibile usare altri tipi di credenziali più sicuri.
VisualStudioCodeCredential

Si connette ad Azure usando le credenziali fornite dall'estensione VSCode "Account Azure". Dopo che l'utente ha effettuato l'accesso tramite l'estensione, questa credenziale può condividere lo stesso token di aggiornamento memorizzato nella cache dall'estensione.

Si tratta di un problema noto che questa credenziale non funziona con le versioni dell'estensione dell'account Azure più recenti di 0.9.11. È in corso una correzione a lungo termine per questo problema. Nel frattempo, valutare la possibilità di eseguire l'autenticazione con AzureCliCredential.
WorkloadIdentityCredential

L'autenticazione dell'identità del carico di lavoro è una funzionalità di Azure che consente alle applicazioni in esecuzione in macchine virtuali (VM) di accedere ad altre risorse di Azure senza la necessità di un'entità servizio o un'identità gestita. Con l'autenticazione dell'identità del carico di lavoro, le applicazioni si autenticano usando la propria identità, invece di usare un'entità servizio condivisa o un'identità gestita. In background, l'autenticazione dell'identità del carico di lavoro usa il concetto di credenziali dell'account del servizio ,create automaticamente da Azure e archiviate in modo sicuro nella macchina virtuale. Usando l'autenticazione dell'identità del carico di lavoro, è possibile evitare la necessità di gestire e ruotare entità servizio o identità gestite per ogni applicazione in ogni macchina virtuale. Inoltre, poiché le schede di sicurezza vengono create automaticamente e gestite da Azure, non è necessario preoccuparsi di archiviare e proteggere le credenziali sensibili. WorkloadIdentityCredential supporta ID dei carichi di lavoro di Microsoft Entra'autenticazione in Azure Kubernetes e acquisisce un token usando le schede di sicurezza disponibili nell'ambiente Azure Kubernetes. Per altre informazioni, vedere ID dei carichi di lavoro di Microsoft Entra.

Interfacce

AccessToken

Rappresenta un token di accesso con una scadenza.
AuthenticationRecord

Record da usare per trovare i token memorizzati nella cache.
AuthenticationRequiredErrorOptions

Parametri facoltativi per AuthenticationRequiredError
AuthorityValidationOptions

Fornisce opzioni per configurare il modo in cui la libreria di identità esegue la convalida dell'autorità durante le richieste di autenticazione per Microsoft Entra ID.
AuthorizationCodeCredentialOptions

Opzioni per AuthorizationCodeCredential
AzureCliCredentialOptions

Opzioni per AzureCliCredential
AzureDeveloperCliCredentialOptions

Opzioni per AzureDeveloperCliCredential
AzurePowerShellCredentialOptions

Opzioni per AzurePowerShellCredential
BrokerAuthOptions

Opzioni di configurazione per InteractiveBrowserCredential per supportare l'autenticazione di WAM Broker.
BrokerDisabledOptions

Parametri quando l'autenticazione del broker WAM è disabilitata.
BrokerEnabledOptions

Parametri quando l'autenticazione del broker WAM è abilitata.
BrowserCustomizationOptions

Opzioni di configurazione condivise per la personalizzazione del browser
ClientAssertionCredentialOptions

Opzioni per ClientAssertionCredential
ClientCertificateCredentialOptions

Parametri facoltativi per la classe ClientCertificateCredential .
ClientCertificatePEMCertificate

Opzioni di configurazione necessarie per ClientCertificateCredential, con il contenuto stringa di un certificato PEM
ClientCertificatePEMCertificatePath

Opzioni di configurazione necessarie per ClientCertificateCredential, con il percorso di un certificato PEM.
ClientSecretCredentialOptions

Parametri facoltativi per la classe ClientSecretCredential .
CredentialPersistenceOptions

Opzioni di configurazione condivise per le credenziali che supportano la memorizzazione nella cache dei token persistenti.
DefaultAzureCredentialClientIdOptions

Fornisce opzioni per configurare la classe DefaultAzureCredential . Questa variante supporta managedIdentityClientId e non managedIdentityResourceId, poiché è supportato solo uno di entrambi.
DefaultAzureCredentialOptions

Fornisce opzioni per configurare la classe DefaultAzureCredential .
DefaultAzureCredentialResourceIdOptions

Fornisce opzioni per configurare la classe DefaultAzureCredential . Questa variante supporta managedIdentityResourceId e non managedIdentityClientId, poiché è supportato solo uno di entrambi.
DeviceCodeCredentialOptions

Definisce le opzioni per la classe InteractiveBrowserCredential per Node.js.
DeviceCodeInfo

Fornisce l'URI di verifica e il codice utente in cui deve essere immesso il codice. Fornisce inoltre un messaggio da visualizzare all'utente che contiene un'istruzione con questi dettagli.
EnvironmentCredentialOptions

Consente l'autenticazione per Microsoft Entra ID a seconda delle variabili di ambiente disponibili. Definisce le opzioni per la classe EnvironmentCredential.
ErrorResponse

Per altri dettagli, vedere la documentazione ufficiale:

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

NOTA: questa documentazione riguarda il supporto OAuth v1, ma gli stessi dettagli della risposta di errore si applicano ancora alla versione 2.
GetBearerTokenProviderOptions

Opzioni per configurare il provider di token.
GetTokenOptions

Definisce le opzioni per TokenCredential.getToken.
InteractiveBrowserCredentialInBrowserOptions

Definisce le opzioni comuni per la classe InteractiveBrowserCredential.
InteractiveBrowserCredentialNodeOptions

Definisce le opzioni comuni per la classe InteractiveBrowserCredential.
InteractiveCredentialOptions

Opzioni comuni del costruttore per le credenziali identity che richiedono l'interazione dell'utente.
ManagedIdentityCredentialClientIdOptions

Opzioni da inviare nel costruttore ManagedIdentityCredential . Questa variante supporta clientId e non resourceId, poiché è supportato solo uno di entrambi.
ManagedIdentityCredentialResourceIdOptions

Opzioni da inviare nel costruttore ManagedIdentityCredential . Questa variante supporta resourceId e non clientId, poiché è supportato solo uno di entrambi.
MultiTenantTokenCredentialOptions

Opzioni per le applicazioni multi-tenant che consentono altri tenant consentiti.
OnBehalfOfCredentialCertificateOptions

Definisce i parametri per autenticare OnBehalfOfCredential con un certificato.
OnBehalfOfCredentialSecretOptions

Definisce i parametri per autenticare OnBehalfOfCredential con un segreto.
TokenCachePersistenceOptions

Parametri che abilitano la persistenza della cache dei token nelle credenziali di identità.
TokenCredential

Rappresenta una credenziale in grado di fornire un token di autenticazione.
TokenCredentialOptions

Fornisce opzioni per configurare il modo in cui la libreria di identità effettua richieste di autenticazione per Microsoft Entra ID.
UsernamePasswordCredentialOptions

Definisce le opzioni per la classe UsernamePasswordCredential .
VisualStudioCodeCredentialOptions

Fornisce opzioni per configurare le credenziali di Visual Studio Code.
WorkloadIdentityCredentialOptions

Opzioni per WorkloadIdentityCredential

Alias tipo

BrokerOptions

Parametri che abilitano l'autenticazione del broker WAM in InteractiveBrowserCredential.
BrowserLoginStyle

(Funzionalità solo browser) Stile di accesso da usare nel flusso di autenticazione:

  • "reindirizzamento" reindirizza l'utente alla pagina di autenticazione e quindi li reindirizza alla pagina al termine dell'autenticazione.
  • "popup" apre una nuova finestra del browser tramite il flusso di reindirizzamento avviato. La finestra del browser esistente dell'utente non lascia la pagina corrente
ClientCertificateCredentialPEMConfiguration

Opzioni di configurazione necessarie per ClientCertificateCredential, con il contenuto stringa di un certificato PEM o il percorso di un certificato PEM.
DeviceCodePromptCallback

Definisce la firma di un callback che verrà passato a DeviceCodeCredential allo scopo di visualizzare i dettagli di autenticazione all'utente.
IdentityPlugin

Tipo di plug-in di Identità di Azure, una funzione che accetta un contesto del plug-in.
OnBehalfOfCredentialOptions

Parametri facoltativi per la classe OnBehalfOfCredential .

Enumerazioni

AzureAuthorityHosts

Elenco degli host di autorità di Azure noti

Funzioni

deserializeAuthenticationRecord(string)

Deserializza un record di autenticazione serializzato in precedenza da una stringa in un oggetto .

La stringa di input deve contenere le proprietà seguenti:

  • "autorità"
  • "homeAccountId"
  • "clientId"
  • "tenantId"
  • "username"
  • "version"

Se la versione ricevuta non è supportata, verrà generato un errore.

Al momento, l'unica versione disponibile è: "1.0", che viene sempre impostata quando il record di autenticazione viene serializzato.
getBearerTokenProvider(TokenCredential, string | string[], GetBearerTokenProviderOptions)

Restituisce un callback che fornisce un token di connessione. Ad esempio, il token di connessione può essere usato per autenticare una richiesta come indicato di seguito:

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

Restituisce una nuova istanza di DefaultAzureCredential.
serializeAuthenticationRecord(AuthenticationRecord)

Serializza un oggetto AuthenticationRecord in una stringa.

L'output di un record di autenticazione serializzato conterrà le proprietà seguenti:

  • "autorità"
  • "homeAccountId"
  • "clientId"
  • "tenantId"
  • "username"
  • "version"

Per convertire successivamente questa stringa in un oggetto serializzato AuthenticationRecord, usare la funzione deserializeAuthenticationRecord()esportata .
useIdentityPlugin(IdentityPlugin)

Estendere l'identità di Azure con funzionalità aggiuntive. Passare un plug-in da un pacchetto plug-in, ad esempio:

  • @azure/identity-cache-persistence: fornisce la memorizzazione nella cache dei token persistenti
  • @azure/identity-vscode: fornisce le dipendenze di VisualStudioCodeCredential e la abilita

Esempio:

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

Dettagli funzione

deserializeAuthenticationRecord(string)

Deserializza un record di autenticazione serializzato in precedenza da una stringa in un oggetto .

La stringa di input deve contenere le proprietà seguenti:

  • "autorità"
  • "homeAccountId"
  • "clientId"
  • "tenantId"
  • "username"
  • "version"

Se la versione ricevuta non è supportata, verrà generato un errore.

Al momento, l'unica versione disponibile è: "1.0", che viene sempre impostata quando il record di autenticazione viene serializzato.

function deserializeAuthenticationRecord(serializedRecord: string): AuthenticationRecord

Parametri

serializedRecord

string

Record di autenticazione serializzato in precedenza in stringa.

Restituisce

AuthenticationRecord

AuthenticationRecord.

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

Restituisce un callback che fornisce un token di connessione. Ad esempio, il token di connessione può essere usato per autenticare una richiesta come indicato di seguito:

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>

Parametri

credential
TokenCredential

Credenziale usata per autenticare la richiesta.

scopes

string | string[]

Ambiti necessari per il token di connessione.

options
GetBearerTokenProviderOptions

Opzioni per configurare il provider di token.

Restituisce

() => Promise<string>

callback che fornisce un token di connessione.

getDefaultAzureCredential()

Restituisce una nuova istanza di DefaultAzureCredential.

function getDefaultAzureCredential(): TokenCredential

Restituisce

TokenCredential

serializeAuthenticationRecord(AuthenticationRecord)

Serializza un oggetto AuthenticationRecord in una stringa.

L'output di un record di autenticazione serializzato conterrà le proprietà seguenti:

  • "autorità"
  • "homeAccountId"
  • "clientId"
  • "tenantId"
  • "username"
  • "version"

Per convertire successivamente questa stringa in un oggetto serializzato AuthenticationRecord, usare la funzione deserializeAuthenticationRecord()esportata .

function serializeAuthenticationRecord(record: AuthenticationRecord): string

Parametri

record
AuthenticationRecord

Restituisce

string

useIdentityPlugin(IdentityPlugin)

Estendere l'identità di Azure con funzionalità aggiuntive. Passare un plug-in da un pacchetto plug-in, ad esempio:

  • @azure/identity-cache-persistence: fornisce la memorizzazione nella cache dei token persistenti
  • @azure/identity-vscode: fornisce le dipendenze di VisualStudioCodeCredential e la abilita

Esempio:

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)

Parametri

plugin
IdentityPlugin

plug-in da registrare