Autentiseringskedjor i Azure identitetsbiblioteket för Java

I Azure Identity-biblioteket finns credentials – offentliga klasser som implementerar Azure Core-bibliotekets TokenCredential-gränssnitt. 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 den autentiseringsuppgiften inte lyckas hämta en åtkomsttoken, försöks nästa autentiseringsuppgift i sekvensen tills en åtkomsttoken har hämtats. Följande sekvensdiagram illustrerar det här beteendet:

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:

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

• 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å olika metoder för identifikationskedja:

• Använd en förkonfigurerad kedja: Börja med en åsiktsbaserad, förkonstruerad kedja som rymmer de vanligaste autentiseringsscenarierna. För denna metod, 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:

Den ordning i vilken DefaultAzureCredential försöker att använda autentiseringsuppgifterna följer.

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

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

// Code omitted for brevity

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

Så här anpassar du DefaultAzureCredential

I följande avsnitt beskrivs strategier för att kontrollera vilka autentiseringsuppgifter som ingår i kedjan.

Exkludera en kategori för autentiseringsuppgifter

Om du vill exkludera alla Developer tool eller Deployed service autentiseringsuppgifter anger du miljövariabeln AZURE_TOKEN_CREDENTIALS till prod respektive dev. När ett värde prod för används ser den underliggande autentiseringskedjan ut så här:

När ett värde dev för används ser kedjan ut så här:

För att säkerställa att miljövariabeln har definierats och angetts till en sträng som stöds anropar du metoden requireEnvVars enligt följande:

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

Om du vill använda ett namn på en anpassad miljövariabel i stället för standardvärdet AZURE_TOKEN_CREDENTIALSanvänder du AzureIdentityEnvVars.fromString() för att skapa en referens till din anpassade variabel:

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .requireEnvVars(AzureIdentityEnvVars.fromString("MY_CUSTOM_TOKEN_CREDENTIALS"))
    .build();

Använda en specifik autentiseringsuppgift

Om du vill exkludera alla autentiseringsuppgifter förutom en anger du miljövariabeln AZURE_TOKEN_CREDENTIALS till namnet på autentiseringsuppgifterna. Du kan till exempel minska DefaultAzureCredential kedjan till AzureCliCredential genom att ange AZURE_TOKEN_CREDENTIALS till AzureCliCredential. Strängjämförelsen görs på ett skiftlägesoberoende sätt. Giltiga strängvärden för miljövariabeln är:

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

För att säkerställa att miljövariabeln har definierats och angetts till en sträng som stöds kräver anropsmetodenEnvVars enligt följande:

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

Översikt över ChainedTokenCredential

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

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

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

Användningsvägledning för DefaultAzureCredential

DefaultAzureCredential är utan tvekan det enklaste sättet att komma igång med Azure identitetsbiblioteket, men med den bekvämligheten kommer kompromisser. När du har distribuerat appen till Azure bör du förstå appens autentiseringskrav och fundera på om DefaultAzureCredential är lämpligt för ditt scenario.

DefaultAzureCredential erbjuder en viktig fördel: den frikopplar programkoden från specifika autentiseringsmekanismer, så att du kan ändra autentiseringskonfigurationen utan att ändra kod. För erfarna utvecklare som medvetet konfigurerar sin produktionsautentisering kan den här flexibiliteten vara värdefull. Den här flexibiliteten medför dock potentiella nackdelar:

• 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 referens till nästa och status för lyckande/misslyckande för varje. 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.
• Unpredictable behavior: DefaultAzureCredential söker efter förekomsten av vissa environmentvariabler. 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 för DefaultAzureCredential vid körning i alla appar som körs på den datorn.
• Behörighetsfel: DefaultAzureCredential stoppas vid den första autentiseringsuppgiften som hämtar en token, oavsett om autentiseringsuppgifterna har rätt behörigheter. Till exempel kan en lokal utvecklingsautentiseringsuppgift ha bredare behörigheter än den produktionshanterade identiteten, vilket gör att appen fungerar lokalt men misslyckas med auktoriseringskontroller efter distributionen.

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.

Anta att den parameterlösa formen DefaultAzureCredential används för att autentisera en begäran till ett Blob Storage konto. Appen körs i den lokala utvecklingsmiljön och utvecklaren autentiseras för att Azure med hjälp av Azure CLI. När appen körs visas följande relevanta poster i utdata:

[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

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

• EnvironmentCredential, WorkloadIdentityCredential, ManagedIdentityCredential, IntelliJCredential och VisualStudioCodeCredential kunde inte hämta en Microsoft Entra åtkomsttoken i den ordningen.
• Anropet AzureCliCredential.getToken lyckas, vilket visas av posten med suffixet returns a token. Sedan AzureCliCredential lyckades har inga autentiseringsuppgifter utöver det prövats.