Azure Identity-clientbibliotheek voor Python - versie 1.14.1
De Azure Identity-bibliotheek biedt ondersteuning voor azure Active Directory-tokenverificatie (Azure AD) in de Azure SDK. Het biedt een set TokenCredential implementaties, die kunnen worden gebruikt om Azure SDK-clients te bouwen die ondersteuning bieden voor Azure AD-tokenverificatie.
Broncode | Pakket (PyPI) | Pakket (Conda) | API-referentiedocumentatie | Azure AD documentatie
Aan de slag
Het pakket installeren
Azure Identity installeren met pip:
pip install azure-identity
Vereisten
- Een Azure-abonnement
- Python 3.7 of een recente versie van Python 3 (deze bibliotheek biedt geen ondersteuning voor end-of-life-versies)
Verifiëren tijdens lokale ontwikkeling
Bij het opsporen en lokaal uitvoeren van code is het gebruikelijk dat ontwikkelaars hun eigen accounts gebruiken voor het verifiëren van aanroepen naar Azure-services. De Azure Identity-bibliotheek ondersteunt verificatie via ontwikkelhulpprogramma's om lokale ontwikkeling te vereenvoudigen.
Verifiëren via Visual Studio Code
Ontwikkelaars die Visual Studio Code gebruiken, kunnen de Azure-accountextensie gebruiken om te verifiëren via de editor. Apps die gebruikmaken van DefaultAzureCredential of VisualStudioCodeCredential kunnen dit account vervolgens gebruiken om aanroepen in hun app te verifiëren wanneer ze lokaal worden uitgevoerd.
Als u wilt verifiëren in Visual Studio Code, moet u ervoor zorgen dat de Azure-accountextensie is geïnstalleerd. Nadat de installatie is uitgevoerd, opent u het opdrachtpalet en voert u de opdracht Azure: Sign In uit.
Het is een bekend probleem dat VisualStudioCodeCredential niet werkt met azure-accountextensieversies nieuwer dan 0.9.11. Er wordt een langetermijnoplossing voor dit probleem uitgevoerd. In de tussentijd kunt u zich verifiëren via de Azure CLI.
Verifiëren via de Azure CLI
DefaultAzureCredential en AzureCliCredential kan verifiëren als de gebruiker die is aangemeld bij de Azure CLI. Voer az loginuit om u aan te melden bij de Azure CLI. Op een systeem met een standaardwebbrowser start de Azure CLI de browser om een gebruiker te verifiëren.
Wanneer er geen standaardbrowser beschikbaar is, az login wordt de verificatiestroom voor apparaatcode gebruikt. Deze stroom kan ook handmatig worden geselecteerd door uit te voeren az login --use-device-code.
Verifiëren via de Azure Developer CLI
Ontwikkelaars die buiten een IDE coderen, kunnen ook de Azure Developer CLI gebruiken om te verifiëren. Toepassingen die de DefaultAzureCredential of gebruiken AzureDeveloperCliCredential , kunnen dit account vervolgens gebruiken om aanroepen in hun toepassing te verifiëren wanneer ze lokaal worden uitgevoerd.
Gebruikers kunnen de opdracht azd auth loginuitvoeren om te verifiëren met de Azure Developer CLI. Voor gebruikers die worden uitgevoerd op een systeem met een standaardwebbrowser, start de Azure Developer CLI de browser om de gebruiker te verifiëren.
Voor systemen zonder een standaardwebbrowser gebruikt de azd auth login --use-device-code opdracht de verificatiestroom voor apparaatcode.
Belangrijkste concepten
Referenties
Een referentie is een klasse die de gegevens bevat of kan verkrijgen die nodig zijn voor een serviceclient om aanvragen te verifiëren. Serviceclients in de Azure SDK accepteren een referentie-exemplaar wanneer ze worden gemaakt en gebruiken die referentie om aanvragen te verifiëren.
De Azure Identity-bibliotheek is gericht op OAuth-verificatie met Azure AD. Het biedt verschillende referentieklassen die een Azure AD toegangstoken kunnen verkrijgen. Zie de sectie Referentieklassen hieronder voor een lijst met referentieklassen van deze bibliotheek.
StandaardAzureCredential
DefaultAzureCredential is geschikt voor de meeste toepassingen die in Azure worden uitgevoerd, omdat algemene productiereferenties worden gecombineerd met ontwikkelingsreferenties. DefaultAzureCredential probeert te verifiëren via de volgende mechanismen, in deze volgorde, stoppen wanneer een slaagt:
Opmerking:
DefaultAzureCredentialis bedoeld om aan de slag te gaan met de bibliotheek te vereenvoudigen door algemene scenario's met redelijk standaardgedrag te verwerken. Ontwikkelaars die meer controle willen of wiens scenario niet wordt geleverd door de standaardinstellingen, moeten andere referentietypen gebruiken.
- Milieu -
DefaultAzureCredentialleest accountgegevens die zijn opgegeven via omgevingsvariabelen en gebruikt deze om te verifiëren. - Workloadidentiteit: als de toepassing is geïmplementeerd in Azure Kubernetes Service waarvoor Beheerde identiteit is ingeschakeld,
DefaultAzureCredentialwordt de verificatie uitgevoerd. - Beheerde identiteit : als de toepassing is geïmplementeerd op een Azure-host waarvoor Beheerde identiteit is ingeschakeld,
DefaultAzureCredentialwordt hiermee geverifieerd. - Azure CLI : als een gebruiker zich heeft aangemeld via de Azure CLI-opdracht
az login,DefaultAzureCredentialwordt deze geverifieerd als die gebruiker. - Azure PowerShell: als een gebruiker zich heeft aangemeld via de opdracht van
Connect-AzAccountAzure PowerShell,DefaultAzureCredentialwordt deze geverifieerd als die gebruiker. - Azure Developer CLI: als de ontwikkelaar is geverifieerd via de opdracht Azure Developer CLI
azd auth login, wordt deDefaultAzureCredentialgeverifieerd met dat account. - Interactieve browser : als deze optie is ingeschakeld,
DefaultAzureCredentialwordt een gebruiker interactief geverifieerd via de standaardbrowser. Dit referentietype is standaard uitgeschakeld.
Opmerking over VisualStudioCodeCredential
Vanwege een bekend probleem is VisualStudioCodeCredential verwijderd uit de DefaultAzureCredential tokenketen. Wanneer het probleem in een toekomstige release is opgelost, wordt deze wijziging teruggedraaid.
Voorbeelden
Hieronder ziet u de volgende voorbeelden:
- Verifiëren met DefaultAzureCredential
- Een aangepaste verificatiestroom definiëren met ChainedTokenCredential
- Asynchrone referenties
Verifiëren met DefaultAzureCredential
Meer informatie over het configureren van uw omgeving voor het gebruik van de DefaultAzureCredential vindt u in de referentiedocumentatie van de klasse.
In dit voorbeeld wordt de geverifieerd BlobServiceClient vanuit de bibliotheek azure-storage-blob met behulp van DefaultAzureCredential.
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient
default_credential = DefaultAzureCredential()
client = BlobServiceClient(account_url, credential=default_credential)
Interactieve verificatie inschakelen met DefaultAzureCredential
Interactieve verificatie is standaard uitgeschakeld in de DefaultAzureCredential en kan worden ingeschakeld met een trefwoordargument:
DefaultAzureCredential(exclude_interactive_browser_credential=False)
Wanneer deze optie is ingeschakeld, DefaultAzureCredential valt u terug op interactief verifiëren via de standaardwebbrowser van het systeem wanneer er geen andere referenties beschikbaar zijn.
Een door de gebruiker toegewezen beheerde identiteit opgeven voor DefaultAzureCredential
Veel Azure-hosts staan de toewijzing van een door de gebruiker toegewezen beheerde identiteit toe. Als u wilt configureren DefaultAzureCredential om een door de gebruiker toegewezen identiteit te verifiëren, gebruikt u het managed_identity_client_id sleutelwoordargument:
DefaultAzureCredential(managed_identity_client_id=client_id)
U kunt ook de omgevingsvariabele AZURE_CLIENT_ID instellen op de client-id van de identiteit.
Een aangepaste verificatiestroom definiëren met ChainedTokenCredential
DefaultAzureCredential is over het algemeen de snelste manier om aan de slag te gaan met het ontwikkelen van toepassingen voor Azure. Voor geavanceerdere scenario's koppelt ChainedTokenCredential meerdere referentie-exemplaren die opeenvolgend moeten worden geprobeerd tijdens de verificatie. Elke gekoppelde referentie wordt op zijn beurt geprobeerd totdat er een token wordt opgegeven of niet kan worden geverifieerd vanwege een fout.
In het volgende voorbeeld ziet u hoe u een referentie maakt die eerst probeert te verifiëren met behulp van een beheerde identiteit. De referentie wordt teruggezet op verificatie via de Azure CLI wanneer een beheerde identiteit niet beschikbaar is. In dit voorbeeld wordt de EventHubProducerClient uit de clientbibliotheek azure-eventhub gebruikt.
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)
Asynchrone referenties
Deze bibliotheek bevat een set asynchrone API's. Als u de asynchrone referenties in azure.identity.aio wilt gebruiken, moet u eerst een asynchroon transport installeren, zoals aiohttp. Zie azure-core-documentatie voor meer informatie.
Asynchrone referenties moeten worden gesloten wanneer ze niet meer nodig zijn. Elke asynchrone referentie is een asynchroon contextbeheer en definieert een asynchrone close methode. Bijvoorbeeld:
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 dit voorbeeld ziet u hoe de asynchrone SecretClient verificatie van azure-keyvault-secrets wordt gebruikt met een asynchrone referentie.
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)
Ondersteuning voor beheerde identiteiten
Verificatie van beheerde identiteit wordt ondersteund via de DefaultAzureCredential of ManagedIdentityCredential rechtstreeks voor de volgende Azure-services:
- Azure App Service en Azure Functions
- Azure Arc
- Azure Cloud Shell
- Azure Kubernetes Service
- Azure Service Fabric
- Azure Virtual Machines
- Azure Virtual Machines-schaalsets
Voorbeelden
Verifiëren met een door de gebruiker toegewezen beheerde identiteit
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)
Verifiëren met een door het systeem toegewezen beheerde identiteit
from azure.identity import ManagedIdentityCredential
from azure.keyvault.secrets import SecretClient
credential = ManagedIdentityCredential()
client = SecretClient("https://my-vault.vault.azure.net", credential)
Cloudconfiguratie
Referenties zijn standaard voor verificatie bij het Azure AD-eindpunt voor Azure Public Cloud. Als u toegang wilt krijgen tot resources in andere clouds, zoals Azure Government of een privécloud, configureert u referenties met het authority argument . AzureAuthorityHosts definieert instanties voor bekende clouds:
from azure.identity import AzureAuthorityHosts
DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)
Als de instantie voor uw cloud niet wordt vermeld in AzureAuthorityHosts, kunt u expliciet de URL opgeven:
DefaultAzureCredential(authority="https://login.partner.microsoftonline.cn")
Als alternatief voor het opgeven van het authority argument kunt u ook de AZURE_AUTHORITY_HOST omgevingsvariabele instellen op de URL van de instantie van uw cloud. Deze aanpak is handig bij het configureren van meerdere referenties voor verificatie bij dezelfde cloud:
AZURE_AUTHORITY_HOST=https://login.partner.microsoftonline.cn
Deze configuratie is niet voor alle referenties vereist. Referenties die worden geverifieerd via een ontwikkelhulpprogramma, zoals AzureCliCredential, gebruiken de configuratie van dat hulpprogramma. Op dezelfde manier accepteert authority een argument, VisualStudioCodeCredential maar wordt standaard de instantie gebruikt die overeenkomt met de instelling 'Azure: Cloud' van VS Code.
Referentieklassen
Door Azure gehoste toepassingen verifiëren
| Referentie | Gebruik |
|---|---|
DefaultAzureCredential |
Biedt een vereenvoudigde verificatie-ervaring om snel te beginnen met het ontwikkelen van toepassingen die worden uitgevoerd in Azure. |
ChainedTokenCredential |
Hiermee kunnen gebruikers aangepaste verificatiestromen definiëren die meerdere referenties samenstellen. |
EnvironmentCredential |
Verifieert een service-principal of gebruiker via referentiegegevens die zijn opgegeven in omgevingsvariabelen. |
ManagedIdentityCredential |
Hiermee wordt de beheerde identiteit van een Azure-resource geverifieerd. |
WorkloadIdentityCredential |
Ondersteunt Azure AD workloadidentiteit in Kubernetes. |
Service-principals verifiëren
| Referentie | Gebruik | Referentie |
|---|---|---|
CertificateCredential |
Verifieert een service-principal met behulp van een certificaat. | Verificatie van service-principal |
ClientAssertionCredential |
Verifieert een service-principal met behulp van een ondertekende clientverklaring. | |
ClientSecretCredential |
Verifieert een service-principal met behulp van een geheim. | Verificatie van service-principal |
Gebruikers verifiëren
| Referentie | Gebruik | Referentie |
|---|---|---|
AuthorizationCodeCredential |
Hiermee wordt een gebruiker geverifieerd met een eerder verkregen autorisatiecode. | OAuth2-verificatiecode |
DeviceCodeCredential |
Hiermee wordt een gebruiker interactief geverifieerd op apparaten met een beperkte gebruikersinterface. | Verificatie van apparaatcode |
InteractiveBrowserCredential |
Hiermee wordt een gebruiker interactief geverifieerd met de standaardsysteembrowser. | OAuth2-verificatiecode |
OnBehalfOfCredential |
Hiermee wordt de gedelegeerde gebruikersidentiteit en machtigingen doorgegeven via de aanvraagketen. | On-behalf-of-verificatie |
UsernamePasswordCredential |
Hiermee wordt een gebruiker geverifieerd met een gebruikersnaam en wachtwoord (biedt geen ondersteuning voor meervoudige verificatie). | Gebruikersnaam en wachtwoordverificatie |
Verifiëren via ontwikkelhulpprogramma's
| Referentie | Gebruik | Referentie |
|---|---|---|
AzureCliCredential |
Verifieert in een ontwikkelomgeving met de Azure CLI. | Azure CLI-verificatie |
AzureDeveloperCliCredential |
Verifieert in een ontwikkelomgeving met de Azure Developer CLI. | Azure Developer CLI naslaginformatie |
AzurePowerShellCredential |
Verifieert in een ontwikkelomgeving met de Azure PowerShell. | Azure PowerShell verificatie |
VisualStudioCodeCredential |
Verifieert als de gebruiker die is aangemeld bij de Azure-accountextensie van Visual Studio Code. | Vs Code Azure-accountextensie |
Omgevingsvariabelen
DefaultAzureCredential en EnvironmentCredential kunnen worden geconfigureerd met omgevingsvariabelen. Voor elk type verificatie zijn waarden vereist voor specifieke variabelen:
Service-principal met geheim
| Naam van de variabele | Waarde |
|---|---|
AZURE_CLIENT_ID |
Id van een Azure AD-toepassing |
AZURE_TENANT_ID |
Id van de Azure AD-tenant van de toepassing |
AZURE_CLIENT_SECRET |
een van de clientgeheimen van de toepassing |
Service-principal met certificaat
| Naam van de variabele | Waarde |
|---|---|
AZURE_CLIENT_ID |
Id van een Azure AD-toepassing |
AZURE_TENANT_ID |
Id van de Azure AD-tenant van de toepassing |
AZURE_CLIENT_CERTIFICATE_PATH |
pad naar een PEM- of PKCS12-certificaatbestand, inclusief persoonlijke sleutel |
AZURE_CLIENT_CERTIFICATE_PASSWORD |
wachtwoord van het certificaatbestand, indien aanwezig |
Gebruikersnaam en wachtwoord
| Naam van de variabele | Waarde |
|---|---|
AZURE_CLIENT_ID |
Id van een Azure AD-toepassing |
AZURE_USERNAME |
een gebruikersnaam (meestal een e-mailadres) |
AZURE_PASSWORD |
het wachtwoord van die gebruiker |
Configuratie wordt geprobeerd in de bovenstaande volgorde. Als er bijvoorbeeld waarden voor een clientgeheim en certificaat aanwezig zijn, wordt het clientgeheim gebruikt.
Token opslaan in cache
Tokencache is een functie van de Azure Identity-bibliotheek waarmee apps het volgende kunnen doen:
- Cachetokens in het geheugen (standaard) of op schijf (opt-in).
- Verbeter de tolerantie en prestaties.
- Verminder het aantal aanvragen voor Azure AD om toegangstokens te verkrijgen.
De Azure Identity-bibliotheek biedt zowel in-memory als permanente schijfcaching. Zie de documentatie over tokencache voor meer informatie.
Problemen oplossen
Zie de handleiding voor probleemoplossing voor meer informatie over het diagnosticeren van verschillende foutscenario's.
Foutafhandeling
Referenties worden weergegeven CredentialUnavailableError wanneer ze geen verificatie kunnen uitvoeren omdat ze geen vereiste gegevens of status hebben. Met EnvironmentCredential wordt deze uitzondering bijvoorbeeld gegenereerd wanneer de onvolledig is.
Referenties worden weergegeven azure.core.exceptions.ClientAuthenticationError wanneer ze niet kunnen worden geverifieerd. ClientAuthenticationError heeft een message kenmerk, waarmee wordt beschreven waarom verificatie is mislukt. Wanneer het bericht wordt gegenereerd door DefaultAzureCredential of ChainedTokenCredential, verzamelt het bericht foutberichten van elke referentie in de keten.
Zie de documentatie over de Azure AD foutcode voor meer informatie over het afhandelen van specifieke Azure AD fouten.
Logboekregistratie
Deze bibliotheek gebruikt de standaardbibliotheek voor logboekregistratie voor logboekregistratie. Basisinformatie over referentieslogboeken, waaronder HTTP-sessies (URL's, headers, enzovoort) op INFO-niveau. Deze logboekvermeldingen bevatten geen verificatiegeheimen.
Gedetailleerde logboekregistratie op foutopsporingsniveau, inclusief aanvraag-/antwoordteksten en headerwaarden, is niet standaard ingeschakeld. Deze kan worden ingeschakeld met het logging_enable argument. Bijvoorbeeld:
credential = DefaultAzureCredential(logging_enable=True)
LET OP: logboeken op foutopsporingsniveau van referenties bevatten gevoelige informatie. Deze logboeken moeten worden beveiligd om te voorkomen dat de accountbeveiliging in gevaar komt.
Volgende stappen
Ondersteuning voor clientbibliotheek
Client- en beheerbibliotheken die worden vermeld op de releasepagina van de Azure SDK die ondersteuning bieden voor Azure AD-verificatie, accepteren referenties uit deze bibliotheek. Meer informatie over het gebruik van deze bibliotheken vindt u in de bijbehorende documentatie, die is gekoppeld op de releasepagina.
Bekende problemen
Deze bibliotheek biedt geen ondersteuning voor Azure AD B2C.
Raadpleeg de GitHub-opslagplaats van de bibliotheek voor andere openstaande problemen.
Feedback geven
Als u fouten tegenkomt of suggesties hebt, opent u een probleem.
Bijdragen
Wij verwelkomen bijdragen en suggesties voor dit project. Voor de meeste bijdragen moet u instemmen met een licentieovereenkomst voor bijdragers (CLA: Contributor License Agreement) waarin u verklaart dat u gerechtigd bent ons het recht te geven uw bijdrage te gebruiken, en dat u dit ook doet. Ga naar https://cla.microsoft.com voor meer informatie.
Wanneer u een pull-aanvraag indient, wordt met een CLA-bot automatisch bepaald of u een CLA moet verschaffen en wordt de pull-aanvraag dienovereenkomstig opgemaakt (bijvoorbeeld met een label of commentaar). Volg gewoon de instructies van de bot. U hoeft dit slechts één keer te doen voor alle opslagplaatsen die onze CLA gebruiken.
Op dit project is de Microsoft Open Source Code of Conduct (Microsoft Open Source-gedragscode) van toepassing. Raadpleeg de Veelgestelde vragen over de gedragscode voor meer informatie of neem contact op met opencode@microsoft.com als u meer vragen of opmerkingen hebt.
