Azure Identity-klientbibliotek för Python – version 1.14.1

  • Artikel

Azure Identity-biblioteket tillhandahåller stöd för Tokenautentisering i Azure Active Directory (Azure AD) i Hela Azure SDK. Den innehåller en uppsättning TokenCredential implementeringar som kan användas för att konstruera Azure SDK-klienter som stöder Azure AD tokenautentisering.

| KällkodPaket (PyPI) | Paket (Conda) | API-referensdokumentation | Azure AD dokumentation

Komma igång

Installera paketet

Installera Azure Identity med pip:

pip install azure-identity

Förutsättningar

  • En Azure-prenumeration
  • Python 3.7 eller en ny version av Python 3 (det här biblioteket stöder inte end-of-life-versioner)

Autentisera under lokal utveckling

När du felsöker och kör kod lokalt är det vanligt att utvecklare använder sina egna konton för att autentisera anrop till Azure-tjänster. Azure Identity-biblioteket stöder autentisering via utvecklarverktyg för att förenkla den lokala utvecklingen.

Autentisera via Visual Studio Code

Utvecklare som använder Visual Studio Code kan använda Azure-kontotillägget för att autentisera via redigeraren. Appar som använder DefaultAzureCredential eller VisualStudioCodeCredential kan sedan använda det här kontot för att autentisera anrop i appen när de körs lokalt.

Om du vill autentisera i Visual Studio Code kontrollerar du att Azure-kontotillägget är installerat. När du har installerat den öppnar du kommandopaletten och kör kommandot Azure: Sign In (Azure: Logga in ).

Det är ett känt problem som VisualStudioCodeCredential inte fungerar med azure-kontotilläggsversioner som är nyare än 0.9.11. En långsiktig korrigering av det här problemet pågår. Under tiden bör du överväga att autentisera via Azure CLI.

Autentisera via Azure CLI

DefaultAzureCredential och AzureCliCredential kan autentiseras när användaren loggade in på Azure CLI. Logga in på Azure CLI genom att köra az login. I ett system med en standardwebbläsare startar Azure CLI webbläsaren för att autentisera en användare.

När ingen standardwebbläsare är tillgänglig az login använder autentiseringsflödet för enhetskod. Det här flödet kan också väljas manuellt genom att köra az login --use-device-code.

Autentisera via Azure Developer CLI

Utvecklare som kodar utanför en IDE kan också använda Azure Developer CLI för att autentisera. Program som använder DefaultAzureCredential eller kan sedan använda det här kontot för att autentisera AzureDeveloperCliCredential anrop i sina program när de körs lokalt.

Om du vill autentisera med Azure Developer CLI kan användarna köra kommandot azd auth login. För användare som kör i ett system med en standardwebbläsare startar Azure Developer CLI webbläsaren för att autentisera användaren.

För system utan en standardwebbläsare azd auth login --use-device-code använder kommandot autentiseringsflödet för enhetskod.

Viktiga begrepp

Merit

En autentiseringsuppgift är en klass som innehåller eller kan hämta de data som behövs för att en tjänstklient ska kunna autentisera begäranden. Tjänstklienter i Azure SDK accepterar en instans av autentiseringsuppgifter när de konstrueras och använder autentiseringsuppgifterna för att autentisera begäranden.

Azure Identity-biblioteket fokuserar på OAuth-autentisering med Azure AD. Den erbjuder olika autentiseringsuppgiftsklasser som kan hämta en Azure AD åtkomsttoken. Se avsnittet Autentiseringsklasser nedan för en lista över bibliotekets autentiseringsklasser.

StandardAzureCredential

DefaultAzureCredential är lämpligt för de flesta program som körs i Azure eftersom det kombinerar vanliga autentiseringsuppgifter för produktion med autentiseringsuppgifter för utveckling. DefaultAzureCredential försöker autentisera via följande mekanismer, i den här ordningen, stoppas när en lyckas:

DefaultAzureCredential Obs! Är avsett att förenkla komma igång med biblioteket genom att hantera vanliga scenarier med rimliga standardbeteenden. Utvecklare som vill ha mer kontroll eller vars scenario inte hanteras av standardinställningarna bör använda andra typer av autentiseringsuppgifter.

DefaultAzureCredential-autentiseringsflöde

  1. Miljö - DefaultAzureCredential läser kontoinformation som anges via miljövariabler och använder den för att autentisera.
  2. Arbetsbelastningsidentitet – Om programmet distribueras till Azure Kubernetes Service med Hanterad identitet aktiverat autentiseras DefaultAzureCredential med det.
  3. Hanterad identitet – Om programmet distribueras till en Azure-värd med Hanterad identitet aktiverat autentiseras DefaultAzureCredential med det.
  4. Azure CLI – Om en användare har loggat in via Azure CLI-kommandot az loginDefaultAzureCredential autentiseras som den användaren.
  5. Azure PowerShell – Om en användare har loggat in via Azure PowerShell-kommandot DefaultAzureCredential autentiseras Connect-AzAccount som den användaren.
  6. Azure Developer CLI – Om utvecklaren har autentiserats via kommandot Azure Developer CLI azd auth login autentiseras DefaultAzureCredential med det kontot.
  7. Interaktiv webbläsare – Om den är aktiverad DefaultAzureCredential autentiseras en användare interaktivt via standardwebbläsaren. Den här typen av autentiseringsuppgifter är inaktiverad som standard.

Obs! VisualStudioCodeCredential

På grund av ett känt problemVisualStudioCodeCredential har tagits bort från DefaultAzureCredential tokenkedjan. När problemet har lösts i en framtida version återställs den här ändringen.

Exempel

Följande exempel finns nedan:

Autentisera med DefaultAzureCredential

Mer information om hur du konfigurerar din miljö att använda DefaultAzureCredential finns i klassens referensdokumentation.

Det här exemplet visar hur du autentiserar BlobServiceClient från biblioteket azure-storage-blob med .DefaultAzureCredential

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

default_credential = DefaultAzureCredential()

client = BlobServiceClient(account_url, credential=default_credential)

Aktivera interaktiv autentisering med DefaultAzureCredential

Interaktiv autentisering är inaktiverat i DefaultAzureCredential som standard och kan aktiveras med ett nyckelordsargument:

DefaultAzureCredential(exclude_interactive_browser_credential=False)

När aktiverad återgår DefaultAzureCredential till interaktiv autentisering via systemets standardwebbläsare när inga andra autentiseringsuppgifter är tillgängliga.

Ange en användartilldelad hanterad identitet för DefaultAzureCredential

Många Azure-värdar tillåter tilldelning av en användartilldelad hanterad identitet. Om du vill konfigurera DefaultAzureCredential för att autentisera en användartilldelad identitet använder du nyckelordsargumentet managed_identity_client_id :

DefaultAzureCredential(managed_identity_client_id=client_id)

Du kan också ange miljövariabeln AZURE_CLIENT_ID till identitetens klient-ID.

Definiera ett anpassat autentiseringsflöde med ChainedTokenCredential

DefaultAzureCredential är vanligtvis det snabbaste sättet att komma igång med att utveckla program för Azure. För mer avancerade scenarier länkar ChainedTokenCredential flera instanser av autentiseringsuppgifter som ska provas sekventiellt vid autentisering. Den kommer att prova varje länkad autentiseringsuppgift i tur och ordning tills en ger en token eller misslyckas med att autentisera på grund av ett fel.

I följande exempel visas hur du skapar en autentiseringsuppgift som först försöker autentisera med hjälp av hanterad identitet. Autentiseringsuppgifterna återgår till autentisering via Azure CLI när en hanterad identitet inte är tillgänglig. I det EventHubProducerClient här exemplet används från azure-eventhub-klientbiblioteket .

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)

Asynkrona autentiseringsuppgifter

Det här biblioteket innehåller en uppsättning asynkrona API:er. Om du vill använda asynkrona autentiseringsuppgifter i azure.identity.aio måste du först installera en asynkron transport, till exempel aiohttp. Mer information finns i dokumentationen om azure-core.

Asynkrona autentiseringsuppgifter bör stängas när de inte längre behövs. Varje asynkron autentiseringsuppgift är en asynkron kontexthanterare och definierar en asynkron close metod. Exempel:

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

Det här exemplet visar hur du autentiserar SecretClient asynkrona från azure-keyvault-secrets med en asynkron autentiseringsuppgift.

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)

Stöd för hanterad identitet

Hanterad identitetsautentisering stöds via antingen DefaultAzureCredential eller ManagedIdentityCredential direkt för följande Azure-tjänster:

Exempel

Autentisera med en användartilldelad hanterad identitet

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)

Autentisera med en systemtilldelad hanterad identitet

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

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

Molnkonfiguration

Autentiseringsuppgifterna är standard för autentisering till Azure AD slutpunkt för azures offentliga moln. Om du vill komma åt resurser i andra moln, till exempel Azure Government eller ett privat moln, konfigurerar du autentiseringsuppgifterna authority med argumentet . AzureAuthorityHosts definierar myndigheter för välkända moln:

from azure.identity import AzureAuthorityHosts

DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)

Om utfärdaren för ditt moln inte finns med i AzureAuthorityHostskan du uttryckligen ange dess URL:

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

Som ett alternativ till att ange authority argumentet kan du också ange AZURE_AUTHORITY_HOST miljövariabeln till URL:en för ditt molns auktoritet. Den här metoden är användbar när du konfigurerar flera autentiseringsuppgifter för att autentisera till samma moln:

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

Alla autentiseringsuppgifter kräver inte den här konfigurationen. Autentiseringsuppgifter som autentiseras via ett utvecklingsverktyg, till exempel AzureCliCredential, använder verktygets konfiguration. VisualStudioCodeCredential På samma sätt accepterar ett authority argument men använder som standard den utfärdare som matchar VS Code-inställningen "Azure: Cloud".

Autentiseringsklasser

Autentisera Azure-värdbaserade program

Autentiseringsuppgift Användning
DefaultAzureCredential Ger en förenklad autentiseringsupplevelse för att snabbt börja utveckla program som körs i Azure.
ChainedTokenCredential Gör att användare kan definiera anpassade autentiseringsflöden som består av flera autentiseringsuppgifter.
EnvironmentCredential Autentiserar tjänstens huvudnamn eller användare via autentiseringsinformation som anges i miljövariabler.
ManagedIdentityCredential Autentiserar den hanterade identiteten för en Azure-resurs.
WorkloadIdentityCredential Stöder Azure AD arbetsbelastningsidentitet på Kubernetes.

Autentisera tjänstens huvudnamn

Autentiseringsuppgift Användning Referens
CertificateCredential Autentiserar ett huvudnamn för tjänsten med hjälp av ett certifikat. Autentisering av tjänstens huvudnamn
ClientAssertionCredential Autentiserar ett huvudnamn för tjänsten med hjälp av en signerad klientkontroll.
ClientSecretCredential Autentiserar ett huvudnamn för tjänsten med hjälp av en hemlighet. Autentisering av tjänstens huvudnamn

Autentisera användare

Autentiseringsuppgift Användning Referens
AuthorizationCodeCredential Autentiserar en användare med en tidigare hämtad auktoriseringskod. OAuth2-autentiseringskod
DeviceCodeCredential Autentiserar en användare interaktivt på enheter med begränsat användargränssnitt. Autentisering med enhetskod
InteractiveBrowserCredential Autentiserar en användare interaktivt med standardsystemwebbläsaren. OAuth2-autentiseringskod
OnBehalfOfCredential Sprider den delegerade användaridentiteten och behörigheterna via begärandekedjan. Å-vägnar för autentisering
UsernamePasswordCredential Autentiserar en användare med ett användarnamn och lösenord (stöder inte multifaktorautentisering). Autentisering med användarnamn och lösenord

Autentisera via utvecklingsverktyg

Autentiseringsuppgift Användning Referens
AzureCliCredential Autentiserar i en utvecklingsmiljö med Azure CLI. Azure CLI-autentisering
AzureDeveloperCliCredential Autentiserar i en utvecklingsmiljö med Azure Developer CLI. Azure Developer CLI referens
AzurePowerShellCredential Autentiserar i en utvecklingsmiljö med Azure PowerShell. Azure PowerShell autentisering
VisualStudioCodeCredential Autentiseras när användaren loggas in på Azure-kontotillägget för Visual Studio Code. AZURE-kontotillägg för VS Code

Miljövariabler

DefaultAzureCredential och EnvironmentCredential kan konfigureras med miljövariabler. Varje typ av autentisering kräver värden för specifika variabler:

Tjänstens huvudnamn med hemlighet

Variabelnamn Värde
AZURE_CLIENT_ID ID för ett Azure AD program
AZURE_TENANT_ID ID för programmets Azure AD klientorganisation
AZURE_CLIENT_SECRET en av programmets klienthemligheter

Tjänstens huvudnamn med certifikat

Variabelnamn Värde
AZURE_CLIENT_ID ID för ett Azure AD program
AZURE_TENANT_ID ID för programmets Azure AD klientorganisation
AZURE_CLIENT_CERTIFICATE_PATH sökväg till en PEM- eller PKCS12-certifikatfil inklusive privat nyckel
AZURE_CLIENT_CERTIFICATE_PASSWORD lösenord för certifikatfilen, om det finns något

Användarnamn och lösenord

Variabelnamn Värde
AZURE_CLIENT_ID ID för ett Azure AD program
AZURE_USERNAME ett användarnamn (vanligtvis en e-postadress)
AZURE_PASSWORD användarens lösenord

Konfigurationen görs i ovanstående ordning. Om det till exempel finns värden för både klienthemligheter och certifikat används klienthemligheten.

Cachelagring av token

Cachelagring av token är en funktion som tillhandahålls av Azure Identity-biblioteket som gör att appar kan:

  • Cachetoken i minnet (standard) eller på disk (anmäl dig).
  • Förbättra motståndskraft och prestanda.
  • Minska antalet begäranden som görs till Azure AD för att hämta åtkomsttoken.

Azure Identity-biblioteket erbjuder både minnesintern och beständig diskcachelagring. Mer information finns i dokumentationen om cachelagring av token.

Felsökning

Mer information om hur du diagnostiserar olika felscenarier finns i felsökningsguiden .

Felhantering

Autentiseringsuppgifterna genereras CredentialUnavailableError när de inte kan försöka autentisera eftersom de saknar nödvändiga data eller tillstånd. Till exempel genererar EnvironmentCredential det här undantaget när är ofullständig.

Autentiseringsuppgifterna genereras azure.core.exceptions.ClientAuthenticationError när de inte kan autentiseras. ClientAuthenticationError har ett message attribut som beskriver varför autentiseringen misslyckades. När det utlöses av DefaultAzureCredential eller ChainedTokenCredentialsamlar meddelandet in felmeddelanden från varje autentiseringsuppgift i kedjan.

Mer information om hur du hanterar specifika Azure AD fel finns i dokumentationen om Azure AD felkod.

Loggning

Det här biblioteket använder standardloggningsbiblioteket för loggning. Grundläggande information om autentiseringsuppgifter loggas, inklusive HTTP-sessioner (URL:er, rubriker osv.) på INFO-nivå. Dessa loggposter innehåller inte autentiseringshemligheter.

Detaljerad loggning på FELSÖKNINGsnivå, inklusive begärande-/svarskroppar och huvudvärden, är inte aktiverat som standard. Det kan aktiveras med logging_enable argumentet . Exempel:

credential = DefaultAzureCredential(logging_enable=True)

VARNING! LOGGAR på FELSÖKNINGsnivå från autentiseringsuppgifter innehåller känslig information. Dessa loggar måste skyddas för att undvika att kontosäkerheten äventyras.

Nästa steg

Stöd för klientbibliotek

Klient- och hanteringsbibliotek som visas på azure SDK-versionssidan som stöder Azure AD autentisering accepterar autentiseringsuppgifter från det här biblioteket. Du kan lära dig mer om hur du använder dessa bibliotek i deras dokumentation, som är länkad från versionssidan.

Kända problem

Det här biblioteket stöder inte Azure AD B2C.

Andra öppna problem finns i bibliotekets GitHub-lagringsplats.

Ge feedback

Om du stöter på buggar eller har förslag kan du öppna ett problem.

Bidra

Det här projektet välkomnar bidrag och förslag. Merparten av bidragen kräver att du godkänner ett licensavtal för bidrag, där du deklarerar att du har behörighet att bevilja oss rättigheten att använda ditt bidrag, och att du dessutom uttryckligen gör så. Mer information finns på https://cla.microsoft.com.

När du skickar en pull-förfrågan avgör en CLA-robot automatiskt om du måste tillhandahålla ett licensavtal för bidrag med lämplig PR (t.ex. etikett eller kommentar). Följ bara robotens anvisningar. Du behöver bara göra detta en gång för alla lagringsplatser med vår CLA.

Det här projektet använder sig av Microsofts uppförandekod för öppen källkod. Du hittar mer information i Vanliga frågor om uppförandekod eller kontakta opencode@microsoft.com för ytterligare frågor eller kommentarer.

Visningar