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.
- Ambiente -
DefaultAzureCredentialleggerà le informazioni sull'account specificate tramite e usarle per l'autenticazione. - Identità del carico di lavoro: se l'applicazione viene distribuita in servizio Azure Kubernetes con l'identità gestita abilitata,
DefaultAzureCredentialeseguirà l'autenticazione con essa. - Identità gestita : se l'applicazione viene distribuita in un host di Azure con identità gestita abilitata,
DefaultAzureCredentiall'autenticazione verrà eseguita con esso. - 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,DefaultAzureCredentialeseguirà l'autenticazione come utente. - Azure PowerShell: se un utente ha eseguito l'accesso tramite il comando di
Connect-AzAccountAzure PowerShell,DefaultAzureCredentialeseguirà l'autenticazione come utente. - Azure Developer CLI: se lo sviluppatore ha eseguito l'autenticazione tramite il comando Azure Developer CLI
azd auth login, l'autenticazioneDefaultAzureCredentialverrà eseguita con tale account. - Browser interattivo : se abilitato,
DefaultAzureCredentialautentica 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
| Credenziale | Utilizzo |
|---|---|
DefaultAzureCredential |
Offre un'esperienza di autenticazione semplificata per iniziare rapidamente a sviluppare applicazioni eseguite in Azure. |
ChainedTokenCredential |
Consente agli utenti di definire flussi di autenticazione personalizzati che compongono più credenziali. |
EnvironmentCredential |
Autentica un'entità servizio o un utente tramite le informazioni sulle credenziali specificate nelle variabili di ambiente. |
ManagedIdentityCredential |
Autentica l'identità gestita di una risorsa di Azure. |
WorkloadIdentityCredential |
Supporta l'identità del carico di lavoro di Azure AD in Kubernetes. |
Autenticare le entità servizio
| Credenziale | Utilizzo | Riferimento |
|---|---|---|
CertificateCredential |
Autentica un'entità servizio usando un certificato. | Autenticazione di un'entità servizio |
ClientAssertionCredential |
Autentica un'entità servizio usando un'asserzione client firmata. | |
ClientSecretCredential |
Autentica un'entità servizio usando un segreto. | Autenticazione di un'entità servizio |
Autenticare gli utenti
| Credenziale | Utilizzo | Riferimento |
|---|---|---|
AuthorizationCodeCredential |
Autentica un utente con un codice di autorizzazione ottenuto in precedenza. | Codice di autenticazione OAuth2 |
DeviceCodeCredential |
Autentica un utente in modo interattivo nei dispositivi con interfaccia utente limitata. | Autenticazione con codice del dispositivo |
InteractiveBrowserCredential |
Autentica un utente in modo interattivo con il browser di sistema predefinito. | Codice di autenticazione OAuth2 |
OnBehalfOfCredential |
Propaga l'identità utente e le autorizzazioni delegate tramite la catena di richieste. | Autenticazione per conto dell'utente |
UsernamePasswordCredential |
Autentica un utente con un nome utente e una password (non supporta l'autenticazione a più fattori). | Autenticazione con nome utente e password |
Eseguire l'autenticazione tramite strumenti di sviluppo
| Credenziale | Utilizzo | Riferimento |
|---|---|---|
AzureCliCredential |
Esegue l'autenticazione in un ambiente di sviluppo con l'interfaccia della riga di comando di Azure. | Autenticazione con interfaccia della riga di comando di Azure |
AzureDeveloperCliCredential |
Esegue l'autenticazione in un ambiente di sviluppo con l'Azure Developer CLI. | Informazioni di riferimento Azure Developer CLI |
AzurePowerShellCredential |
Esegue l'autenticazione in un ambiente di sviluppo con l'Azure PowerShell. | Azure PowerShell autenticazione |
VisualStudioCodeCredential |
Esegue l'autenticazione come utente connesso all'estensione dell'account di Azure di Visual Studio Code. | Estensione Azure Account per Visual Studio Code |
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
| Nome variabile | Valore |
|---|---|
AZURE_CLIENT_ID |
ID di un'applicazione Azure AD |
AZURE_TENANT_ID |
ID del tenant di Azure AD dell'applicazione |
AZURE_CLIENT_SECRET |
Uno dei segreti client dell'applicazione |
Entità servizio con certificato
| Nome variabile | Valore |
|---|---|
AZURE_CLIENT_ID |
ID di un'applicazione Azure AD |
AZURE_TENANT_ID |
ID del tenant di Azure AD dell'applicazione |
AZURE_CLIENT_CERTIFICATE_PATH |
percorso di un file di certificato PEM o PKCS12, inclusa la chiave privata |
AZURE_CLIENT_CERTIFICATE_PASSWORD |
password del file di certificato, se presente |
Nome utente e password
| Nome variabile | Valore |
|---|---|
AZURE_CLIENT_ID |
ID di un'applicazione Azure AD |
AZURE_USERNAME |
Nome utente (in genere un indirizzo di posta elettronica) |
AZURE_PASSWORD |
Password di tale utente |
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.
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per