Referentieketens in de Azure Identity-bibliotheek voor Java

De Azure Identity-bibliotheek 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 inloggegevens 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:

Waarom referentieketens gebruiken

Een gekoppelde referentie kan 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 overgaat naar de volgende inloggegevens wanneer de vorige geen toegangstoken verkrijgt.

Hoe kies je een gekoppelde referentie?

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 voor deze aanpak de DefaultAzureCredential-overzicht sectie.
• '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 doelbewust 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.

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

Hoe pas je DefaultAzureCredential aan

In de volgende secties worden strategieën beschreven voor het beheren van welke referenties in de keten zijn opgenomen.

Een categorie referentietype uitsluiten

Als u alle Developer tool of Deployed service referenties wilt uitsluiten, stelt u de omgevingsvariabele AZURE_TOKEN_CREDENTIALSprod in op respectievelijk dev. Wanneer een waarde van prod wordt gebruikt, ziet de onderliggende referentieketen er als volgt uit:

Wanneer een waarde van dev wordt gebruikt, ziet de keten er als volgt uit:

Om ervoor te zorgen dat de omgevingsvariabele is gedefinieerd en ingesteld op een ondersteunde tekenreeks, roept u de methode requireEnvVars als volgt aan:

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .requireEnvVars(AzureIdentityEnvVars.AZURE_TOKEN_CREDENTIALS)
    .build();

Een specifieke referentie gebruiken

Als u alle referenties behalve één wilt uitsluiten, stelt u de omgevingsvariabele AZURE_TOKEN_CREDENTIALS in op de naam van de referentie. U kunt bijvoorbeeld de keten beperken door deze DefaultAzureCredential in te stellen AzureCliCredential op AZURE_TOKEN_CREDENTIALS.AzureCliCredential De tekenreeksvergelijking wordt op een niet-hoofdlettergevoelige manier uitgevoerd. Geldige tekenreekswaarden voor de omgevingsvariabele zijn:

• AzureCliCredential
• AzureDeveloperCliCredential
• AzurePowerShellCredential
• EnvironmentCredential
• IntelliJCredential
• ManagedIdentityCredential
• VisualStudioCodeCredential
• WorkloadIdentityCredential

Om ervoor te zorgen dat de omgevingsvariabele is gedefinieerd en is ingesteld op een ondersteunde tekenreeks, is de aanroepmethode requireEnvVars als volgt:

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .requireEnvVars(AzureIdentityEnvVars.AZURE_TOKEN_CREDENTIALS)
    .build();

Overzicht ChainedTokenCredential

ChainedTokenCredential is een lege keten waaraan u referenties toevoegt volgens 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.IntelliJCredential;
import com.azure.identity.IntelliJCredentialBuilder;

// Code omitted for brevity

AzureCliCredential cliCredential = new AzureCliCredentialBuilder()
    .build();
IntelliJCredential ijCredential = new IntelliJCredentialBuilder()
    .build();

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

In het voorgaande codevoorbeeld wordt een aangepaste inloggegevensketen gemaakt die bestaat uit twee ontwikkeltijd-inloggegevens. AzureCliCredential wordt eerst geprobeerd, gevolgd door IntelliJCredential, indien nodig. In grafische vorm ziet de keten er als volgt uit:

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. Voor meer informatie, zie Fouten opsporen in een gekoppelde referentie.
• Prestatieoverhead: het proces waarbij meerdere referenties opeenvolgend worden geprobeerd, kan leiden tot prestatieoverhead. Wanneer een beheerde identiteit op een lokale ontwikkelcomputer draait, is deze niet beschikbaar. ManagedIdentityCredential mislukt daarom 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 draait in de lokale ontwikkelomgeving en authenticeerde de ontwikkelaar zich 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 IntelliJCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential VisualStudioCodeCredential 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, , IntelliJCredentialen VisualStudioCodeCredential elk kan in die volgorde geen Microsoft Entra-toegangstoken verkrijgen.
• De AzureCliCredential.getToken aanroep slaagt, zoals aangegeven door de vermelding met het achtervoegsel returns a token. Aangezien AzureCliCredential is geslaagd, zijn er daarna geen verdere inloggegevens geprobeerd.