Delen via

Referentieketens in de Azure Identity-bibliotheek voor Python

  • Artikel

De Azure Identity-bibliotheek biedt referenties: openbare klassen waarmee het TokenCredential-protocol van de Azure Core-bibliotheek wordt geïmplementeerd. Een inloggegeven vertegenwoordigt een afzonderlijk verificatieproces voor het verkrijgen van een toegangstoken van Microsoft Entra ID. Deze referenties kunnen worden gekoppeld om een geordende reeks verificatiemechanismen te vormen die moeten worden geprobeerd.

Hoe een gekoppelde referentie werkt

Tijdens runtime probeert een referentieketen te verifiëren met behulp van de eerste referentie van de reeks. Als deze referentie geen toegangstoken kan verkrijgen, wordt de volgende referentie in de reeks geprobeerd, enzovoort, totdat een toegangstoken is verkregen. In het volgende sequentiediagram ziet u dit gedrag:

diagram dat de volgorde van referentieketens weergeeft.

Waarom referentieketens gebruiken

Een gekoppelde geloofsbrief kan de volgende voordelen bieden:

  • Omgevingsbewustzijn: selecteert automatisch de meest geschikte referentie op basis van de omgeving waarin de app wordt uitgevoerd. Zonder deze code moet u als volgt code schrijven:

    # 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()

  • Naadloze overgangen: uw app kan overstappen van lokale ontwikkeling naar uw faserings- of productieomgeving zonder verificatiecode te wijzigen.

  • Verbeterde veerkracht: bevat een terugvalmechanisme dat overschakelt naar het volgende referentiepunt wanneer het voorgaande geen toegangstoken kan verkrijgen.

Hoe kies je een gekoppelde referentie?

Er zijn twee verschillende filosofieën voor het koppelen van referenties:

Overzicht van DefaultAzureCredential

DefaultAzureCredential is een weloverwogen, vooraf geconfigureerde keten van referenties. Het is ontworpen om veel omgevingen te ondersteunen, samen met de meest voorkomende verificatiestromen en ontwikkelhulpprogramma's. In grafische vorm ziet de onderliggende keten er als volgt uit:

Diagram waarin de defaultAzureCredential-verificatiestroom wordt weergegeven.

De volgorde waarin DefaultAzureCredential inloggegevens worden geprobeerd, is als volgt.

Bestelling Bevoegdheidsbewijs Beschrijving Standaard ingeschakeld?
1 Omgeving Leest een verzameling omgevingsvariabelen om te bepalen of een toepassingsservice-principal (toepassingsgebruiker) is geconfigureerd voor de app. Als dat het zo is, DefaultAzureCredential gebruikt u deze waarden om de app te verifiëren bij Azure. Deze methode wordt meestal gebruikt in serveromgevingen, maar kan ook worden gebruikt bij het lokaal ontwikkelen. Ja
2 Workload Identity Als de app is geïmplementeerd op een Azure-host waarvoor workloadidentiteit is ingeschakeld, verifieert u dat account. Ja
3 Beheerde identiteit Als de app is geïmplementeerd op een Azure-host waarvoor Managed Identity is ingeschakeld, verifieert u de app bij Azure met behulp van die beheerde identiteit. Ja
4 Gedeelde Tokencache Als de ontwikkelaar zich alleen in Windows heeft geverifieerd bij Azure door u aan te melden bij Visual Studio, verifieert u de app bij Azure met hetzelfde account. Ja
5 Azure-CLI Als de ontwikkelaar is geverifieerd bij Azure met behulp van de opdracht van az login Azure CLI, moet u de app verifiëren bij Azure met hetzelfde account. Ja
6 Azure PowerShell Als de ontwikkelaar is geverifieerd bij Azure met behulp van de cmdlet van Connect-AzAccount Azure PowerShell, moet u de app verifiëren bij Azure met hetzelfde account. Ja
7 Azure Developer CLI Als de ontwikkelaar zich heeft geverifieerd bij Azure met behulp van de Azure Developer CLI-opdracht azd auth login, moet u zich met datzelfde account verifiëren. Ja
8 Interactieve browser Indien ingeschakeld, verifieert u de ontwikkelaar interactief via de standaardbrowser van het huidige systeem. Nee

In de eenvoudigste vorm kunt u de parameterloze versie als DefaultAzureCredential volgt gebruiken:

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
)

Hoe pas je DefaultAzureCredential aan

Als u een referentie van DefaultAzureCredential wilt verwijderen, gebruikt u de bijbehorende exclude-voorvoegsel parameter voor het trefwoord. Voorbeeld:

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

In het voorgaande codevoorbeeld EnvironmentCredential en WorkloadIdentityCredential worden ze verwijderd uit de referentieketen. Als gevolg hiervan is ManagedIdentityCredentialde eerste referentie die moet worden geprobeerd. De gewijzigde keten ziet er als volgt uit:

Diagram dat de verificatiestroom laat zien voor een DefaultAzureCredential-exemplaar na het gebruik van trefwoordparameters met het voorvoegsel exclude in de constructor om de omgevingsreferentie en workload-identiteitsreferentie te verwijderen.

Notitie

InteractiveBrowserCredential is standaard uitgesloten en wordt daarom niet weergegeven in het voorgaande diagram. Om InteractiveBrowserCredential op te nemen, stelt u de exclude_interactive_browser_credential trefwoordparameter in op False wanneer u de DefaultAzureCredential constructor aanroept.

Naarmate er meer exclude-voorvoegselparameters voor trefwoorden worden ingesteld als True (zoals referentieuitsluitingen worden geconfigureerd), nemen de voordelen van het gebruik van DefaultAzureCredential af. In dergelijke gevallen ChainedTokenCredential is dit een betere keuze en is minder code vereist. Ter illustratie gedragen deze twee codevoorbeelden zich op dezelfde manier:

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
)

ChainedTokenCredential overzicht

ChainedTokenCredential is een lege keten waaraan u referentiegegevens toevoegt om aan de behoeften van uw app te voldoen. Voorbeeld:

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

In het voorgaande codevoorbeeld wordt een aangepaste referentieketen gemaakt die bestaat uit twee referenties voor ontwikkeltijd. AzureCliCredential wordt eerst geprobeerd, gevolgd door AzureDeveloperCliCredential, indien nodig. In grafische vorm ziet de keten er als volgt uit:

diagram met de verificatiestroom voor een ChainedTokenCredential-exemplaar dat bestaat uit Azure CLI- en Azure Developer CLI-referenties.

Tip

Voor betere prestaties optimaliseert u de volgorde van referenties in ChainedTokenCredential van de meeste naar de minst gebruikte referenties.

Gebruiksrichtlijnen voor DefaultAzureCredential

DefaultAzureCredential is ongetwijfeld de eenvoudigste manier om aan de slag te gaan met de Azure Identity-bibliotheek, maar dat gemak brengt ook nadelen met zich mee. Zodra u uw app in Azure hebt geïmplementeerd, moet u de verificatievereisten van de app begrijpen. Vervang daarom DefaultAzureCredential door een specifieke TokenCredential-implementatie, zoals ManagedIdentityCredential.

Hier is waarom:

  • Problemen met foutopsporing: wanneer verificatie mislukt, kan het lastig zijn om fouten op te sporen en de referentie te identificeren. U moet logboekregistratie inschakelen om de voortgang te zien van de ene referentie naar de volgende en de succes-/foutstatus van elke referentie. Zie Fouten opsporen in een gekoppelde referentie voor meer informatie.
  • Prestatieoverhead: het proces waarbij meerdere referenties opeenvolgend worden geprobeerd, kan leiden tot prestatieoverhead. Wanneer bijvoorbeeld een lokale ontwikkelcomputer wordt gebruikt, is een beheerde identiteit niet beschikbaar. De ManagedIdentityCredential faalt dus altijd in de lokale ontwikkelomgeving, tenzij expliciet uitgeschakeld via de bijbehorende eigenschap met exclude-prefix.
  • Onvoorspelbaar gedrag: DefaultAzureCredential controleert op de aanwezigheid van bepaalde omgevingsvariabelen. Het is mogelijk dat iemand deze omgevingsvariabelen kan toevoegen of wijzigen op systeemniveau op de hostcomputer. Deze wijzigingen zijn globaal van toepassing en wijzigen daarom het gedrag van DefaultAzureCredential tijdens runtime in elke app die op die computer wordt uitgevoerd.

Fouten opsporen in een gekoppelde inloggegevens

Als u een onverwacht probleem wilt vaststellen of wilt weten wat een gekoppelde referentie doet, schakelt u logboekregistratie in uw app in. U kunt de logboeken desgewenst filteren op alleen de gebeurtenissen die zijn verzonden uit de Azure Identity-clientbibliotheek. Voorbeeld:

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)}"
)

Voor illustratiedoeleinden wordt ervan uitgegaan dat de parameterloze vorm wordt gebruikt voor het verifiëren van DefaultAzureCredential een aanvraag voor een blob-opslagaccount. De app draait in de lokale ontwikkelomgeving en de ontwikkelaar heeft zich geverifieerd bij Azure met de Azure CLI. Stel ook dat het logboekregistratieniveau is ingesteld op logging.DEBUG. Wanneer de app wordt uitgevoerd, worden de volgende relevante vermeldingen weergegeven in de uitvoer:

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

In de voorgaande uitvoer ziet u dat:

  • EnvironmentCredential, ManagedIdentityCredentialen SharedTokenCacheCredential elk kan in die volgorde geen Microsoft Entra-toegangstoken verkrijgen.
  • De AzureCliCredential.get_token aanroep slaagt en de uitvoer geeft ook aan dat DefaultAzureCredential een token is verkregen van AzureCliCredential. Aangezien AzureCliCredential is geslaagd, zijn er geen verdere inloggegevens geprobeerd.

Notitie

In het voorgaande voorbeeld is het niveau van de logboekregistratie ingesteld op logging.DEBUG. Wees voorzichtig bij het gebruik van dit logboekregistratieniveau, omdat het gevoelige informatie kan uitvoeren. In dit geval bijvoorbeeld de client-id, tenant-id en de object-id van het gebruikersaccount van de ontwikkelaar in Azure. Alle traceringsinformatie is voor duidelijkheid verwijderd uit de uitvoer.