Dela via


Autentiseringskedjor i Azure Identity-biblioteket för Python

Azure Identity-biblioteket innehåller autentiseringsuppgifter– offentliga klasser som implementerar Azure Core-bibliotekets protokoll TokenCredential. En autentiseringsuppgift representerar ett distinkt autentiseringsflöde för att hämta en åtkomsttoken från Microsoft Entra-ID. Dessa autentiseringsuppgifter kan kopplas samman för att bilda en ordnad sekvens med autentiseringsmekanismer som ska försökas.

Så här fungerar en länkad autentiseringsuppgift

Vid körning försöker en autentiseringskedja autentisera med sekvensens första autentiseringsuppgifter. Om autentiseringsuppgifter misslyckas med att hämta en åtkomsttoken, försöks nästa autentiseringsuppgifter i ordningen, och så vidare, tills en åtkomsttoken har hämtats. Följande sekvensdiagram illustrerar det här beteendet:

diagram som visar autentiseringskedjans sekvens.

Varför använda autentiseringskedjor

En länkad autentiseringsuppgift kan erbjuda följande fördelar:

  • Miljömedvetenhet: Väljer automatiskt de lämpligaste autentiseringsuppgifterna baserat på miljön där appen körs. Utan den skulle du behöva skriva kod så här:

    # Set up credential based on environment (Azure or local development)
    if os.getenv("WEBSITE_HOSTNAME"):
        credential = ManagedIdentityCredential(client_id=user_assigned_client_id)
    else:
        credential = AzureCliCredential()
    
  • Sömlösa övergångar: Din app kan gå från lokal utveckling till mellanlagrings- eller produktionsmiljön utan att ändra autentiseringskoden.

  • Förbättrad återhämtning: Innehåller en återställningsmekanism som flyttas till nästa autentiseringsuppgift när den föregående misslyckas med att hämta en åtkomsttoken.

Så här väljer du en länkad autentiseringsuppgift

Det finns två skilda filosofier för uppgiftskedjning.

  • "Riv ned" en kedja: Börja med en förkonfigurerad kedja och uteslut det du inte behöver. För den här metoden, se avsnittet DefaultAzureCredential-översikt.
  • "Bygg upp" en kedja: Börja med en tom kedja och inkludera bara det du behöver. Den här metoden finns i översiktsavsnittet ChainedTokenCredential.

Översikt över DefaultAzureCredential

DefaultAzureCredential är en åsiktsbaserad, förkonfigurerad kedja med autentiseringsuppgifter. Den är utformad för att stödja många miljöer, tillsammans med de vanligaste autentiseringsflödena och utvecklarverktygen. I grafisk form ser den underliggande kedjan ut så här:

Diagram som visar autentiseringsflödet DefaultAzureCredential.

Den ordning som DefaultAzureCredential autentiseringsförsöken följer.

Order Behörighet beskrivning Aktiverat som standard?
1 Miljö Läser en samling miljövariabler för att avgöra om ett programtjänsthuvudnamn (programanvändare) har konfigurerats för appen. I så fall DefaultAzureCredential använder du dessa värden för att autentisera appen till Azure. Den här metoden används oftast i servermiljöer men kan också användas när du utvecklar lokalt. Ja
2 Arbetsbelastningsidentitet Om appen distribueras till en Azure-värd med aktiverad arbetsbelastningsidentitet, autentisera kontot. Ja
3 Hanterad identitet Om appen distribueras till en Azure-värd med hanterad identitet aktiverad autentiserar du appen till Azure med hjälp av den hanterade identiteten. Ja
4 Delad Token-cache Endast i Windows, om utvecklaren autentiserades till Azure genom att logga in på Visual Studio, autentisera appen till Azure med samma konto. Ja
5 Azure CLI Om utvecklaren autentiserade till Azure med hjälp av Azure CLI:s az login kommando autentiserar du appen till Azure med samma konto. Ja
6 Azure PowerShell Om utvecklaren autentiserade till Azure med hjälp av Azure PowerShells Connect-AzAccount cmdlet autentiserar du appen till Azure med samma konto. Ja
7 Azure Developer CLI Om utvecklaren autentiserade till Azure med hjälp av Azure Developer CLI:s azd auth login kommando autentiserar du med det kontot. Ja
8 Interaktiv webbläsare Om det är aktiverat autentiserar du utvecklaren interaktivt via det aktuella systemets standardwebbläsare. Nej

I sin enklaste form kan du använda den parameterlösa versionen av DefaultAzureCredential på följande sätt:

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

# Acquire a credential object
credential = DefaultAzureCredential()

blob_service_client = BlobServiceClient(
    account_url="https://<my_account_name>.blob.core.windows.net",
    credential=credential
)

Så här anpassar du DefaultAzureCredential

Om du vill ta bort en autentiseringsuppgift från DefaultAzureCredential, använd motsvarande exclude-prefixet nyckelordsparameter. Till exempel:

credential = DefaultAzureCredential(
    exclude_environment_credential=True, 
    exclude_workload_identity_credential=True,
    managed_identity_client_id=user_assigned_client_id
)

I det föregående kodexemplet tas EnvironmentCredential och WorkloadIdentityCredential bort från certifikatkedjan. Därför är ManagedIdentityCredentialden första autentiseringsuppgiften som ska försökas . Den ändrade kedjan ser ut så här:

Diagram som visar autentiseringsflödet för en DefaultAzureCredential-instans efter att ha använt nyckelordsparametrar med exkluderingsprefix i konstruktorn för att ta bort miljöautentiseringsuppgifter och arbetsbelastningsidentitetsautentiseringsuppgifter.

Anteckning

InteractiveBrowserCredential exkluderas som standard och visas därför inte i föregående diagram. Om du vill inkludera InteractiveBrowserCredentialanger du nyckelordsparametern exclude_interactive_browser_credential till False när du anropar DefaultAzureCredential konstruktorn.

Eftersom fler exclude-prefixerade nyckelordsparametrar anges till True (undantag för autentiseringsuppgifter har konfigurerats) minskar fördelarna med att använda DefaultAzureCredential . I sådana fall ChainedTokenCredential är ett bättre val och kräver mindre kod. För att illustrera fungerar dessa två kodexempel på samma sätt:

credential = DefaultAzureCredential(
    exclude_environment_credential=True,
    exclude_workload_identity_credential=True,
    exclude_shared_token_cache_credential=True,
    exclude_azure_powershell_credential=True,
    exclude_azure_developer_cli_credential=True,
    managed_identity_client_id=user_assigned_client_id
)

Översikt över ChainedTokenCredential

ChainedTokenCredential är en tom kedja som du lägger till autentiseringsuppgifter till för att passa appens behov. Till exempel:

credential = ChainedTokenCredential(
    AzureCliCredential(),
    AzureDeveloperCliCredential()
)

Föregående kodexempel skapar en anpassad autentiseringskedja som består av två autentiseringsuppgifter för utvecklingstid. AzureCliCredential försöks först, följt av AzureDeveloperCliCredential, om det behövs. I grafisk form ser kedjan ut så här:

diagram som visar autentiseringsflödet för en ChainedTokenCredential-instans som består av autentiseringsuppgifter för Azure CLI och Azure Developer CLI.

Tips

För bättre prestanda optimerar du ordning på autentiseringsuppgifter i ChainedTokenCredential från de flesta till minst använda autentiseringsuppgifterna.

Användningsvägledning för DefaultAzureCredential

DefaultAzureCredential är utan tvekan det enklaste sättet att komma igång med Azure Identity-biblioteket, men med den bekvämligheten kommer kompromisser. När du har distribuerat din app till Azure bör du förstå appens autentiseringskrav. Därför ersätter du DefaultAzureCredential med en specifik TokenCredential implementering, till exempel ManagedIdentityCredential.

Här är varför:

  • Felsökningsutmaningar: När autentiseringen misslyckas kan det vara svårt att felsöka och identifiera de felaktiga autentiseringsuppgifterna. Du måste aktivera loggning för att se förloppet från en identifieringsuppgift till nästa och statusen för lyckades/misslyckades för var och en. Mer information finns i Felsöka en länkad autentiseringsuppgift.
  • Prestandakostnader: Processen med att sekventiellt prova flera autentiseringsuppgifter kan medföra prestandakostnader. När den till exempel körs på en lokal utvecklingsdator är den hanterade identiteten inte tillgänglig. Därför ManagedIdentityCredential misslyckas alltid i den lokala utvecklingsmiljön, såvida den inte uttryckligen inaktiveras via motsvarande excludeprefixegenskap.
  • Oförutsägbart beteende: DefaultAzureCredential söker efter förekomsten av vissa miljövariabler. Det är möjligt att någon kan lägga till eller ändra dessa miljövariabler på systemnivå på värddatorn. Dessa ändringar gäller globalt och ändrar därför beteendet DefaultAzureCredential för vid körning i alla appar som körs på den datorn.

Felsöka en länkad autentiseringsuppgift

Om du vill diagnostisera ett oväntat problem eller förstå vad en länkad autentiseringsuppgift gör aktiverar du loggning i din app. Du kan också filtrera loggarna till endast de händelser som genereras från Azure Identity-klientbiblioteket. Till exempel:

import logging
from azure.identity import DefaultAzureCredential

# Set the logging level for the Azure Identity library
logger = logging.getLogger("azure.identity")
logger.setLevel(logging.DEBUG)

# Direct logging output to stdout. Without adding a handler,
# no logging output is visible.
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# Optional: Output logging levels to the console.
print(
    f"Logger enabled for ERROR={logger.isEnabledFor(logging.ERROR)}, "
    f"WARNING={logger.isEnabledFor(logging.WARNING)}, "
    f"INFO={logger.isEnabledFor(logging.INFO)}, "
    f"DEBUG={logger.isEnabledFor(logging.DEBUG)}"
)

I illustrationssyfte förutsätter vi att den parameterlösa formen av DefaultAzureCredential används för att autentisera en begäran till ett bloblagringskonto. Appen körs i den lokala utvecklingsmiljön och utvecklaren autentiseras till Azure med hjälp av Azure CLI. Anta också att loggningsnivån är inställd på logging.DEBUG. När appen körs visas följande relevanta poster i utdata:

Logger enabled for ERROR=True, WARNING=True, INFO=True, DEBUG=True
No environment configuration found.
ManagedIdentityCredential will use IMDS
EnvironmentCredential.get_token failed: EnvironmentCredential authentication unavailable. Environment variables are not fully configured.
Visit https://aka.ms/azsdk/python/identity/environmentcredential/troubleshoot to troubleshoot this issue.
ManagedIdentityCredential.get_token failed: ManagedIdentityCredential authentication unavailable, no response from the IMDS endpoint.     
SharedTokenCacheCredential.get_token failed: SharedTokenCacheCredential authentication unavailable. No accounts were found in the cache.
AzureCliCredential.get_token succeeded
[Authenticated account] Client ID: 00001111-aaaa-2222-bbbb-3333cccc4444. Tenant ID: aaaabbbb-0000-cccc-1111-dddd2222eeee. User Principal Name: unavailableUpn. Object ID (user): aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb
DefaultAzureCredential acquired a token from AzureCliCredential

Observera följande i föregående utdata:

  • EnvironmentCredential, ManagedIdentityCredentialoch SharedTokenCacheCredential kunde inte hämta en Microsoft Entra-åtkomsttoken i den ordningen.
  • Anropet AzureCliCredential.get_token lyckas och utdata anger också att DefaultAzureCredential hämtade en token från AzureCliCredential. Sedan AzureCliCredential lyckades har inga autentiseringsuppgifter utöver det prövats.

Kommentar

I föregående exempel är loggningsnivån inställd på logging.DEBUG. Var försiktig när du använder den här loggningsnivån eftersom den kan mata ut känslig information. I det här fallet, till exempel, klient-ID, hyresvärd-ID och objekt-ID för utvecklarens användarhuvudkonto i Azure. All spårningsinformation har tagits bort från utdata för tydlighetens skull.