Azure Identity-clientbibliotheek voor Python - versie 1.14.1

  • Artikel

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: DefaultAzureCredential is 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.

DefaultAzureCredential-verificatiestroom

  1. Milieu - DefaultAzureCredential leest accountgegevens die zijn opgegeven via omgevingsvariabelen en gebruikt deze om te verifiëren.
  2. Workloadidentiteit: als de toepassing is geïmplementeerd in Azure Kubernetes Service waarvoor Beheerde identiteit is ingeschakeld, DefaultAzureCredential wordt de verificatie uitgevoerd.
  3. Beheerde identiteit : als de toepassing is geïmplementeerd op een Azure-host waarvoor Beheerde identiteit is ingeschakeld, DefaultAzureCredential wordt hiermee geverifieerd.
  4. Azure CLI : als een gebruiker zich heeft aangemeld via de Azure CLI-opdracht az login , DefaultAzureCredential wordt deze geverifieerd als die gebruiker.
  5. Azure PowerShell: als een gebruiker zich heeft aangemeld via de opdracht van Connect-AzAccount Azure PowerShell, DefaultAzureCredential wordt deze geverifieerd als die gebruiker.
  6. Azure Developer CLI: als de ontwikkelaar is geverifieerd via de opdracht Azure Developer CLIazd auth login, wordt de DefaultAzureCredential geverifieerd met dat account.
  7. Interactieve browser : als deze optie is ingeschakeld, DefaultAzureCredential wordt 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

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:

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.

Weergaven