Libreria client di Identità di Azure per Python - versione 1.14.1

La libreria di identità di Azure offre il supporto per l'autenticazione token di Azure Active Directory (Azure AD) in Azure SDK. Fornisce un set di TokenCredential implementazioni, che possono essere usate per creare client azure SDK che supportano l'autenticazione del token di Azure AD.

Codice | sorgentePacchetto (PyPI) | Pacchetto (Conda) | Documentazione di | riferimento sulle APIDocumentazione di Azure AD

Introduzione

Installare il pacchetto

Installare l'identità di Azure con pip:

pip install azure-identity

Prerequisiti

• Una sottoscrizione di Azure
• Python 3.7 o una versione recente di Python 3 (questa libreria non supporta versioni end-of-life)

Eseguire l'autenticazione durante lo sviluppo locale

Quando si esegue il debug e l'esecuzione di codice in locale, è tipico per gli sviluppatori usare i propri account per l'autenticazione delle chiamate ai servizi di Azure. La libreria di identità di Azure supporta l'autenticazione tramite strumenti di sviluppo per semplificare lo sviluppo locale.

Eseguire l'autenticazione tramite Visual Studio Code

Gli sviluppatori che usano Visual Studio Code possono usare l'estensione account di Azure per eseguire l'autenticazione tramite l'editor. Le app che usano DefaultAzureCredential o VisualStudioCodeCredential possono quindi usare questo account per autenticare le chiamate nell'app durante l'esecuzione in locale.

Per eseguire l'autenticazione in Visual Studio Code, verificare che l'estensione dell'account di Azure sia installata. Dopo l'installazione, aprire il riquadro comandi ed eseguire il comando Azure: Accedi .

Si tratta di un problema noto che VisualStudioCodeCredential non funziona con le versioni dell'estensione account di Azure più recenti di 0.9.11. Una correzione a lungo termine a questo problema è in corso. Nel frattempo, prendere in considerazione l'autenticazione tramite l'interfaccia della riga di comando di Azure.

Eseguire l'autenticazione tramite l'interfaccia della riga di comando di Azure

DefaultAzureCredential e AzureCliCredential può eseguire l'autenticazione come utente connesso all'interfaccia della riga di comando di Azure. Per accedere all'interfaccia della riga di comando di Azure, eseguire az login. In un sistema con un Web browser predefinito, l'interfaccia della riga di comando di Azure avvia il browser per autenticare un utente.

Quando non è disponibile alcun browser predefinito, az login userà il flusso di autenticazione del codice del dispositivo. Questo flusso può essere selezionato manualmente eseguendo az login --use-device-code.

Eseguire l'autenticazione tramite il Azure Developer CLI

Gli sviluppatori che eseguono la codifica all'esterno di un IDE possono usare anche la Azure Developer CLI per l'autenticazione. Le applicazioni che usano DefaultAzureCredential o AzureDeveloperCliCredential possono quindi autenticare le chiamate nell'applicazione con questo account durante l'esecuzione in locale.

Per eseguire l'autenticazione con il Azure Developer CLI, gli utenti possono eseguire il comando azd auth login. Per gli utenti in esecuzione in un sistema con un Web browser predefinito, il Azure Developer CLI avvierà il browser per autenticare l'utente.

Per i sistemi senza un Web browser predefinito, il comando azd auth login --use-device-code userà il flusso di autenticazione del codice del dispositivo.

Concetti chiave

Credenziali

Una credenziale è una classe contenente o può ottenere i dati necessari per un client del servizio per autenticare le richieste. I client di servizio in Azure SDK accettano un'istanza delle credenziali quando vengono costruite e usano tale credenziale per autenticare le richieste.

La libreria di identità di Azure è incentrata sull'autenticazione OAuth con Azure AD. Offre diverse classi di credenziali in grado di acquisire un token di accesso di Azure AD. Per un elenco delle classi di credenziali di questa libreria, vedere la sezione Classi di credenziali di seguito.

DefaultAzureCredential

DefaultAzureCredential è appropriato per la maggior parte delle applicazioni eseguite in Azure perché combina le credenziali di produzione comuni con le credenziali di sviluppo. DefaultAzureCredential tenta di eseguire l'autenticazione tramite i meccanismi seguenti, in questo ordine, arrestarsi quando uno ha esito positivo:

Nota: DefaultAzureCredential è destinato a semplificare l'introduzione alla libreria gestendo scenari comuni con comportamenti predefiniti ragionevoli. Gli sviluppatori che vogliono un maggior controllo o i cui requisiti non vengono soddisfatti dalle impostazioni predefinite dovranno usare altri tipi di credenziali.

1. Ambiente - DefaultAzureCredential leggerà le informazioni sull'account specificate tramite e usarle per l'autenticazione.
2. Identità del carico di lavoro: se l'applicazione viene distribuita in servizio Azure Kubernetes con l'identità gestita abilitata, DefaultAzureCredential eseguirà l'autenticazione con essa.
3. Identità gestita : se l'applicazione viene distribuita in un host di Azure con identità gestita abilitata, DefaultAzureCredential l'autenticazione verrà eseguita con esso.
4. Interfaccia della riga di comando di Azure: se un utente ha eseguito l'accesso tramite il comando dell'interfaccia della riga di comando di Azure az login , DefaultAzureCredential eseguirà l'autenticazione come utente.
5. Azure PowerShell: se un utente ha eseguito l'accesso tramite il comando di Connect-AzAccount Azure PowerShell, DefaultAzureCredential eseguirà l'autenticazione come utente.
6. Azure Developer CLI: se lo sviluppatore ha eseguito l'autenticazione tramite il comando Azure Developer CLIazd auth login, l'autenticazione DefaultAzureCredential verrà eseguita con tale account.
7. Browser interattivo : se abilitato, DefaultAzureCredential autentica in modo interattivo un utente tramite il browser predefinito. Questo tipo di credenziali è disabilitato per impostazione predefinita.

Nota su VisualStudioCodeCredential

A causa di un problema noto, VisualStudioCodeCredential è stato rimosso dalla DefaultAzureCredential catena di token. Quando il problema viene risolto in una versione futura, questa modifica verrà ripristinata.

Esempio

Di seguito sono riportati gli esempi seguenti:

• Eseguire l'autenticazione con DefaultAzureCredential
• Definire un flusso di autenticazione personalizzato con ChainedTokenCredential
• Credenziali asincrone

Eseguire l'autenticazione con DefaultAzureCredential

Altre informazioni sulla configurazione dell'ambiente da usare DefaultAzureCredential sono disponibili nella documentazione di riferimento della classe.

Questo esempio illustra l'autenticazione BlobServiceClient da azure-storage-BLOB library usando DefaultAzureCredential.

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient

default_credential = DefaultAzureCredential()

client = BlobServiceClient(account_url, credential=default_credential)

Abilitare l'autenticazione interattiva con DefaultAzureCredential

L'autenticazione DefaultAzureCredential interattiva è disabilitata per impostazione predefinita e può essere abilitata con un argomento parola chiave:

DefaultAzureCredential(exclude_interactive_browser_credential=False)

Se abilitato, DefaultAzureCredential torna all'autenticazione interattiva tramite il Web browser predefinito del sistema quando non è disponibile alcuna altra credenziale.

Specificare un'identità gestita assegnata dall'utente per DefaultAzureCredential

Molti host di Azure consentono l'assegnazione di un'identità gestita assegnata dall'utente. Per configurare DefaultAzureCredential l'autenticazione di un'identità assegnata dall'utente, usare l'argomento managed_identity_client_id parola chiave:

DefaultAzureCredential(managed_identity_client_id=client_id)

In alternativa, impostare la variabile AZURE_CLIENT_ID di ambiente sull'ID client dell'identità.

Definire un flusso di autenticazione personalizzato con ChainedTokenCredential

DefaultAzureCredential è in genere il modo più rapido per iniziare a sviluppare applicazioni per Azure. Per scenari più avanzati, ChainedTokenCredential collega più istanze delle credenziali da provare in sequenza durante l'autenticazione. Prova ogni credenziale concatenata a sua volta fino a quando non fornisce un token o non riesce a eseguire l'autenticazione a causa di un errore.

Nell'esempio seguente viene illustrata la creazione di una credenziale che tenterà prima di eseguire l'autenticazione usando l'identità gestita. Le credenziali torneranno all'autenticazione tramite l'interfaccia della riga di comando di Azure quando un'identità gestita non è disponibile. In questo esempio viene EventHubProducerClient usato dalla libreria client azure-eventhub .

from azure.eventhub import EventHubProducerClient
from azure.identity import AzureCliCredential, ChainedTokenCredential, ManagedIdentityCredential

managed_identity = ManagedIdentityCredential()
azure_cli = AzureCliCredential()
credential_chain = ChainedTokenCredential(managed_identity, azure_cli)

client = EventHubProducerClient(namespace, eventhub_name, credential_chain)

Credenziali asincrone

Questa libreria include un set di API asincrone. Per usare le credenziali asincrone in azure.identity.aio, è prima necessario installare un trasporto asincrono, ad esempio aiohttp. Per altre informazioni, vedere la documentazione di azure-core.

Le credenziali asincrone devono essere chiuse quando non sono più necessarie. Ogni credenziale asincrona è una gestione contesto asincrona e definisce un metodo asincrono close . Ad esempio:

from azure.identity.aio import DefaultAzureCredential

# call close when the credential is no longer needed
credential = DefaultAzureCredential()
...
await credential.close()

# alternatively, use the credential as an async context manager
credential = DefaultAzureCredential()
async with credential:
  ...

In questo esempio viene illustrata l'autenticazione asincrona dai segreti azure-keyvault-con credenziali asincroneSecretClient.

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient

default_credential = DefaultAzureCredential()
client = SecretClient("https://my-vault.vault.azure.net", default_credential)

Supporto delle identità gestite

L'autenticazione dell'identitàDefaultAzureCredential gestita è supportata tramite o ManagedIdentityCredential direttamente per i servizi di Azure seguenti:

• Servizio app di Azure e Funzioni di Azure
• Azure Arc
• Azure Cloud Shell
• Servizio Azure Kubernetes
• Azure Service Fabric
• Macchine virtuali di Azure
• Set di scalabilità di Azure Macchine virtuali

Esempio

Eseguire l'autenticazione con un'identità gestita assegnata dall'utente

from azure.identity import ManagedIdentityCredential
from azure.keyvault.secrets import SecretClient

credential = ManagedIdentityCredential(client_id=managed_identity_client_id)
client = SecretClient("https://my-vault.vault.azure.net", credential)

Eseguire l'autenticazione con un'identità gestita assegnata dal sistema

from azure.identity import ManagedIdentityCredential
from azure.keyvault.secrets import SecretClient

credential = ManagedIdentityCredential()
client = SecretClient("https://my-vault.vault.azure.net", credential)

Configurazione del cloud

Credenziali predefinite per l'autenticazione all'endpoint di Azure AD per Azure Public Cloud. Per accedere alle risorse in altri cloud, ad esempio Azure per enti pubblici o un cloud privato, configurare le credenziali con l'argomentoauthority. AzureAuthorityHosts definisce le autorità per i cloud noti:

from azure.identity import AzureAuthorityHosts

DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)

Se l'autorità per il cloud non è elencata in AzureAuthorityHosts, è possibile specificarne in modo esplicito l'URL:

DefaultAzureCredential(authority="https://login.partner.microsoftonline.cn")

In alternativa, specificare l'argomento authority , è anche possibile impostare la AZURE_AUTHORITY_HOST variabile di ambiente sull'URL dell'autorità del cloud. Questo approccio è utile quando si configurano più credenziali per l'autenticazione nello stesso cloud:

AZURE_AUTHORITY_HOST=https://login.partner.microsoftonline.cn

Non tutte le credenziali richiedono questa configurazione. Credenziali che eseguono l'autenticazione tramite uno strumento di sviluppo, ad esempio AzureCliCredential, usano la configurazione di tale strumento. Analogamente, accetta un authority argomento, VisualStudioCodeCredential ma per impostazione predefinita l'autorità corrispondente all'impostazione "Azure: Cloud" di VS Code.

Classi di credenziali

Autenticare le applicazioni ospitate in Azure

Autenticare le entità servizio

Autenticare gli utenti

Eseguire l'autenticazione tramite strumenti di sviluppo

Variabili di ambiente

DefaultAzureCredential e EnvironmentCredential possono essere configurati con variabili di ambiente. Ogni tipo di autenticazione richiede i valori per le variabili specifiche:

Entità servizio con segreto

Entità servizio con certificato

Nome utente e password

La configurazione viene eseguita nell'ordine precedente. Se ad esempio sono presenti sia i valori di un segreto client che quelli di un certificato, verrà usato il segreto client.

Memorizzazione nella cache dei token

La memorizzazione nella cache dei token è una funzionalità fornita dalla libreria di identità di Azure che consente alle app di:

• Token di cache in memoria (impostazione predefinita) o su disco (consenso esplicito).
• Migliorare la resilienza e le prestazioni.
• Ridurre il numero di richieste effettuate in Azure AD per ottenere i token di accesso.

La libreria di identità di Azure offre la memorizzazione nella cache dei dischi persistenti e in memoria. Per altre informazioni, vedere la documentazione sulla memorizzazione nella cache dei token.

Risoluzione dei problemi

Per informazioni dettagliate su come diagnosticare vari scenari di errore, vedere la guida alla risoluzione dei problemi .

Gestione degli errori

Le credenziali generano CredentialUnavailableError quando non sono in grado di tentare l'autenticazione perché non hanno dati o stato necessari. Ad esempio, EnvironmentCredential genererà questa eccezione quando è incompleta.

Le credenziali generano azure.core.exceptions.ClientAuthenticationError quando non riescono a eseguire l'autenticazione. ClientAuthenticationError ha un message attributo, che descrive il motivo per cui l'autenticazione non è riuscita. Quando generato da DefaultAzureCredential o ChainedTokenCredential, il messaggio raccoglie i messaggi di errore da ogni credenziale nella catena.

Per altre informazioni sulla gestione di errori di Azure AD specifici, vedere la documentazione del codice di errore di Azure AD.

Registrazione

Questa libreria usa la libreria di registrazione standard per la registrazione. Informazioni di base sul log delle credenziali, incluse le sessioni HTTP (URL, intestazioni e così via) a livello di INFO. Queste voci di log non contengono segreti di autenticazione.

La registrazione dettagliata del livello DEBUG, inclusi i corpi di richiesta/risposta e i valori di intestazione, non è abilitata per impostazione predefinita. Può essere abilitata con l'argomento logging_enable . Ad esempio:

credential = DefaultAzureCredential(logging_enable=True)

ATTENZIONE: i log a livello di DEBUG dalle credenziali contengono informazioni riservate. Questi log devono essere protetti per evitare di compromettere la sicurezza degli account.

Passaggi successivi

Supporto della libreria client

Librerie client e di gestione elencate nella pagina di versione di Azure SDK che supportano l'autenticazione di Azure AD accettano le credenziali da questa libreria. Altre informazioni sull'uso di queste librerie sono disponibili nella relativa documentazione, collegata dalla pagina di rilascio.

Problemi noti

Questa libreria non supporta Azure AD B2C.

Per altri problemi aperti, vedere il repository GitHub della libreria.

Inviare commenti e suggerimenti

Se si verificano bug o si hanno suggerimenti, aprire un problema.

Contributo

In questo progetto sono benvenuti i contributi e i suggerimenti. Per la maggior parte dei contenuti è necessario sottoscrivere un contratto di licenza di collaborazione (CLA, Contributor License Agreement) che stabilisce che l'utente ha il diritto di concedere, e di fatto concede a Microsoft i diritti d'uso del suo contributo. Per informazioni dettagliate, vedere https://cla.microsoft.com.

Quando si invia una richiesta pull, un bot CLA determina automaticamente se è necessario specificare un contratto CLA e completare la richiesta pull in modo appropriato (ad esempio con un'etichetta e un commento). Seguire le istruzioni specificate dal bot. È sufficiente eseguire questa operazione una sola volta in tutti i repository usando la cla.

Questo progetto ha adottato il Codice di comportamento di Microsoft per l'open source. Per altre informazioni, vedere Code of Conduct FAQ (Domande frequenti sul Codice di comportamento) oppure contattare opencode@microsoft.com per eventuali altre domande o commenti.