Referentieketens in de Azure Identity-clientbibliotheek voor Java

Artikel
11/12/2024

De Azure Identity-clientbibliotheek biedt referenties: openbare klassen die de TokenCredential-interface van de Azure Core-bibliotheek implementeren. Een referentie vertegenwoordigt een afzonderlijke verificatiestroom 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 waarin de reeks referentieketens wordt weergegeven.

Waarom referentieketens gebruiken

Een gekoppelde referentie 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:

import com.azure.core.credential.TokenCredential;
import com.azure.identity.AzureCliCredentialBuilder;
import com.azure.identity.ManagedIdentityCredentialBuilder;

// Code omitted for brevity

TokenCredential credential = null;

// Set up credential based on environment (Azure or local development)
String environment = System.getenv("ENV");

if (environment != null && environment.equals("production")) {
    credential = new ManagedIdentityCredentialBuilder()
        .clientId(userAssignedClientId)
        .build();
} else {
    credential = new AzureCliCredentialBuilder()
        .build();
}

Naadloze overgangen: uw app kan overstappen van lokale ontwikkeling naar uw faserings- of productieomgeving zonder verificatiecode te wijzigen.
Verbeterde tolerantie: bevat een terugvalmechanisme dat naar de volgende referentie wordt verplaatst wanneer het voorgaande geen toegangstoken kan verkrijgen.

Een gekoppelde referentie kiezen

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

Gebruik een vooraf geconfigureerde keten: Begin met een vooraf geconstrueerde, vooraf samengestelde keten die geschikt is voor de meest voorkomende verificatiescenario's. Zie de overzichtssectie DefaultAzureCredential voor deze aanpak.
'Bouw' een keten op: Begin met een lege keten en neem alleen op wat u nodig hebt. Zie de overzichtssectie ChainedTokenCredential voor deze aanpak.

Overzicht van DefaultAzureCredential

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

De volgorde waarin DefaultAzureCredential referenties worden geprobeerd, volgt.

Order	Referentie	Beschrijving
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.
2	Workloadidentiteit	Als de app is geïmplementeerd op een Azure-host waarvoor workloadidentiteit is ingeschakeld, verifieert u dat account.
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.
4	Gedeelde tokencache	Als de ontwikkelaar zich bij Azure heeft geverifieerd door u aan te melden bij Visual Studio, moet u de app verifiëren bij Azure met hetzelfde account. (Alleen Windows.)
5	IntelliJ	Als de ontwikkelaar is geverifieerd via Azure Toolkit voor IntelliJ, moet u dat account verifiëren.
6	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.
7	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.
8	Azure Developer CLI	Als de ontwikkelaar is geverifieerd bij Azure met behulp van de opdracht van `azd auth login` Azure Developer CLI, moet u zich verifiëren met dat account.

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

import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;

// Code omitted for brevity

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .build();

Overzicht chainedTokenCredential

ChainedTokenCredential is een lege keten waaraan u referenties toevoegt aan de behoeften van uw app. Voorbeeld:

import com.azure.identity.AzureCliCredential;
import com.azure.identity.AzureCliCredentialBuilder;
import com.azure.identity.ChainedTokenCredential;
import com.azure.identity.ChainedTokenCredentialBuilder;
import com.azure.identity.ManagedIdentityCredential;
import com.azure.identity.ManagedIdentityCredentialBuilder;

// Code omitted for brevity

ManagedIdentityCredential miCredential = new ManagedIdentityCredentialBuilder()
    .clientId(userAssignedClientId)
    .build();
AzureCliCredential cliCredential = new AzureCliCredentialBuilder()
    .build();

ChainedTokenCredential credential = new ChainedTokenCredentialBuilder()
    .addLast(miCredential)
    .addLast(cliCredential)
    .build();

In het voorgaande codevoorbeeld wordt een aangepaste referentieketen gemaakt die bestaat uit twee referenties. De door de gebruiker toegewezen beheerde identiteitvariant wordt ManagedIdentityCredential eerst geprobeerd, gevolgd door AzureCliCredential, indien nodig. In grafische vorm ziet de keten er als volgt uit:

Diagram met verificatiestroom voor een ChainedTokenCredential-exemplaar dat bestaat uit referenties voor beheerde identiteit en Azure CLI-referenties.

Tip

Voor betere prestaties optimaliseert u de volgorde van referenties voor ChainedTokenCredential uw productieomgeving. Referenties die zijn bedoeld voor gebruik in de lokale ontwikkelomgeving, moeten als laatste worden toegevoegd.

Gebruiksrichtlijnen voor DefaultAzureCredential

DefaultAzureCredential is ongetwijfeld de eenvoudigste manier om aan de slag te gaan met de Azure Identity-clientbibliotheek, maar met dat gemak komt het van pas. Zodra u uw app in Azure hebt geïmplementeerd, moet u de verificatievereisten van de app begrijpen. Daarom kunt u het beste overstappen van DefaultAzureCredential een van de volgende oplossingen:

Een specifieke referentie-implementatie, zoals ManagedIdentityCredential.
Een geparseerde implementatie die is geoptimaliseerd voor de Azure-omgeving ChainedTokenCredential waarin uw app wordt uitgevoerd.

Waarom is:

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 een beheerde identiteit bijvoorbeeld wordt uitgevoerd op een lokale ontwikkelcomputer, is de beheerde identiteit niet beschikbaar. ManagedIdentityCredential Daarom mislukt altijd in de lokale ontwikkelomgeving.
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 referentie

Als u een onverwacht probleem wilt vaststellen of wilt weten wat een gekoppelde referentie doet, schakelt u logboekregistratie in uw app in.

Voor illustratiedoeleinden wordt ervan uitgegaan dat de parameterloze vorm van wordt gebruikt voor het verifiëren van DefaultAzureCredential een aanvraag voor een Blob Storage-account. De app wordt uitgevoerd in de lokale ontwikkelomgeving en de ontwikkelaar die is geverifieerd bij Azure met behulp van de Azure CLI. Wanneer de app wordt uitgevoerd, worden de volgende relevante vermeldingen weergegeven in de uitvoer:

[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential EnvironmentCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential WorkloadIdentityCredential is unavailable.
[ForkJoinPool.commonPool-worker-1] WARN com.microsoft.aad.msal4j.ConfidentialClientApplication - [Correlation ID: aaaa0000-bb11-2222-33cc-444444dddddd] Execution of class com.microsoft.aad.msal4j.AcquireTokenByClientCredentialSupplier failed: java.util.concurrent.ExecutionException: com.azure.identity.CredentialUnavailableException: ManagedIdentityCredential authentication unavailable. Connection to IMDS endpoint cannot be established.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential ManagedIdentityCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential SharedTokenCacheCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential IntelliJCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential AzureCliCredential returns a token

In de voorgaande uitvoer ziet u dat:

EnvironmentCredential, , WorkloadIdentityCredentialManagedIdentityCredential, , SharedTokenCacheCredentialen IntelliJCredential elk kan in die volgorde geen Microsoft Entra-toegangstoken verkrijgen.
De AzureCliCredential.getToken aanroep slaagt, zoals aangegeven door de returns a tokenvermelding -suffixed. Omdat AzureCliCredential het is gelukt, zijn er geen referenties meer geprobeerd.

Delen via