Azure Identity-klientbibliotek för Python – version 1.14.1
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:
DefaultAzureCredentialObs! Ä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.
- Miljö -
DefaultAzureCredentialläser kontoinformation som anges via miljövariabler och använder den för att autentisera. - Arbetsbelastningsidentitet – Om programmet distribueras till Azure Kubernetes Service med Hanterad identitet aktiverat autentiseras
DefaultAzureCredentialmed det. - Hanterad identitet – Om programmet distribueras till en Azure-värd med Hanterad identitet aktiverat autentiseras
DefaultAzureCredentialmed det. - Azure CLI – Om en användare har loggat in via Azure CLI-kommandot
az loginDefaultAzureCredentialautentiseras som den användaren. - Azure PowerShell – Om en användare har loggat in via Azure PowerShell-kommandot
DefaultAzureCredentialautentiserasConnect-AzAccountsom den användaren. - Azure Developer CLI – Om utvecklaren har autentiserats via kommandot Azure Developer CLI
azd auth loginautentiserasDefaultAzureCredentialmed det kontot. - Interaktiv webbläsare – Om den är aktiverad
DefaultAzureCredentialautentiseras 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
- Definiera ett anpassat autentiseringsflöde med ChainedTokenCredential
- Asynkrona autentiseringsuppgifter
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:
- Azure App Service och Azure Functions
- Azure Arc
- Azure Cloud Shell
- Azure Kubernetes Service
- Azure Service Fabric
- Azure Virtual Machines
- Skalningsuppsättningar för Azure Virtual Machines
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.
