Catene di credenziali nella libreria delle identità di Azure per Java

La libreria Azure Identity fornisce credentials—classi pubbliche che implementano l'interfaccia TokenCredential della libreria Azure Core. Una credenziale rappresenta un flusso di autenticazione distinto per l'acquisizione di un token di accesso da Microsoft Entra ID. Queste credenziali si possono concatenare per formare una sequenza ordinata di meccanismi di autenticazione da tentare.

Funzionamento di una credenziale concatenata

In fase di esecuzione, una catena di credenziali tenta di eseguire l'autenticazione usando la prima credenziale della sequenza. Se tale credenziale non riesce ad acquisire un token di accesso, viene tentata la credenziale successiva nella sequenza e così via finché non viene ottenuto un token di accesso correttamente. Il diagramma di sequenza seguente illustra questo comportamento:

Perché usare le catene di credenziali

Una credenziale concatenata può offrire i vantaggi seguenti:

• Riconoscimento dell'ambiente: seleziona automaticamente la credenziale più adeguata in base all'ambiente di esecuzione dell'app. Senza di essa, si dovrebbe scrivere un codice simile al seguente:

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

• transizioni semplici: l'app può passare dallo sviluppo locale all'ambiente di staging o di produzione senza modificare il codice di autenticazione.

• Resilienza migliorata: include un meccanismo di fallback che passa alla credenziale successiva se quella precedente non riesce ad acquisire un token di accesso.

Come scegliere una credenziale concatenata

Esistono due approcci diversi per il concatenamento delle credenziali:

• Usare una catena preconfigurata: iniziare con una catena con opinioni preconstruite che supporta gli scenari di autenticazione più comuni. Per questo approccio, consultare la sezione panoramica di DefaultAzureCredential.
• "Creare" una catena: iniziare da una catena vuota e includere solo ciò che serve. Per questo approccio, vedere la sezione panoramica di ChainedTokenCredential.

Panoramica di DefaultAzureCredential

DefaultAzureCredential è una catena di credenziali preconfigurata e con opinioni definite. È progettata per supportare molti ambienti, insieme ai flussi di autenticazione e agli strumenti di sviluppo più comuni. Graficamente, la catena sottostante è simile alla seguente:

L'ordine in cui DefaultAzureCredential tenta le credenziali è il seguente.

Nella sua forma più semplice, è possibile usare la versione senza parametri di DefaultAzureCredential, come indicato di seguito:

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

// Code omitted for brevity

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

Come personalizzare DefaultAzureCredential

Le sezioni seguenti descrivono le strategie per controllare quali credenziali sono incluse nella catena.

Escludere una categoria del tipo di credenziale

Per escludere tutte le credenziali Developer tool o Deployed service , impostare la variabile di ambiente AZURE_TOKEN_CREDENTIALS rispettivamente su prod o dev. Quando viene usato un valore di prod , la catena di credenziali sottostante è simile alla seguente:

Quando viene usato un valore di dev , la catena ha l'aspetto seguente:

Per assicurarsi che la variabile di ambiente sia definita e impostata su una stringa supportata, chiamare il metodo requireEnvVars come indicato di seguito:

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

Per usare un nome di variabile di ambiente personalizzato anziché quello predefinito, usare AZURE_TOKEN_CREDENTIALS per creare un riferimento alla variabile personalizzataAzureIdentityEnvVars.fromString():

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

Usare credenziali specifiche

Per escludere tutte le credenziali ad eccezione di una, impostare la variabile AZURE_TOKEN_CREDENTIALS di ambiente sul nome delle credenziali. Ad esempio, è possibile ridurre la catena DefaultAzureCredential a AzureCliCredential impostando AZURE_TOKEN_CREDENTIALS su AzureCliCredential. Il confronto tra stringhe viene eseguito senza distinzione tra maiuscole e minuscole. I valori stringa validi per la variabile di ambiente includono:

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

Per assicurarsi che la variabile di ambiente sia definita e impostata su una stringa supportata, chiamare il metodo requireEnvVars come indicato di seguito:

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

Panoramica di ChainedTokenCredential

ChainedTokenCredential è una catena vuota a cui aggiungere le credenziali in base alle esigenze dell'app. Ad esempio:

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

L'esempio di codice precedente crea una catena di credenziali personalizzata costituita da due credenziali in fase di sviluppo. Si tenta AzureCliCredential per primo, seguito da IntelliJCredential, se necessario. Graficamente, la catena è simile alla seguente:

Linee guida sull'utilizzo di DefaultAzureCredential

DefaultAzureCredential è senza dubbio il modo più semplice per iniziare a usare la libreria di identità Azure, ma con tale praticità si verifica un compromesso. Dopo aver distribuito l'app in Azure, è necessario comprendere i requisiti di autenticazione dell'app e valutare se DefaultAzureCredential è appropriato per lo scenario in uso.

DefaultAzureCredential offre un vantaggio fondamentale: separa il codice dell'applicazione da meccanismi di autenticazione specifici, consentendo di modificare la configurazione di autenticazione senza modificare il codice. Per gli sviluppatori esperti che configurano con consapevolezza l'autenticazione di produzione, questa flessibilità può essere utile. Tuttavia, questa flessibilità presenta potenziali svantaggi:

• Problematiche di debug: quando l'autenticazione non va a buon fine, può essere difficile eseguire il debug e l'identificazione della credenziale all'origine dell'errore. È necessario abilitare la registrazione per visualizzare il passaggio da una credenziale alla successiva e lo stato di esito positivo/negativo di ognuna di esse. Per altre informazioni, vedere la sezione Eseguire il debug di una credenziale concatenata.
• sovraccarico delle prestazioni: il processo di tentativo sequenziale di più credenziali può comportare un sovraccarico delle prestazioni. Ad esempio, se si esegue l'app in un computer di sviluppo locale, l'identità gestita non è disponibile. Di conseguenza, ManagedIdentityCredential ha sempre esito negativo nell'ambiente di sviluppo locale.
• Unpredictable behavior: DefaultAzureCredential verifica la presenza di determinate variabili d'ambiente. È possibile che un utente possa aggiungere o modificare queste variabili di ambiente a livello di sistema nel computer host. Tali modifiche si applicano a livello globale e quindi modificano il comportamento di DefaultAzureCredential in fase di runtime in qualsiasi app in esecuzione in tale computer.
• Incongruenze nelle autorizzazioni: DefaultAzureCredential si ferma alla prima credenziale che acquisisce correttamente un token, indipendentemente dal fatto che tale credenziale disponga delle autorizzazioni corrette. Ad esempio, una credenziale di sviluppo locale potrebbe avere autorizzazioni più ampie rispetto all'identità gestita di produzione, permettendo all'app di funzionare correttamente in locale, ma portando al fallimento dei controlli di autorizzazione dopo la distribuzione.

Eseguire il debug di credenziali concatenate

Per diagnosticare un problema imprevisto o per comprendere le operazioni di una credenziale concatenata, abilitare la registrazione nell'app.

A scopo illustrativo, si supponga che venga usata la forma senza parametri di DefaultAzureCredential per autenticare una richiesta a un account Blob Storage. L'app viene eseguita nell'ambiente di sviluppo locale e lo sviluppatore ha eseguito l'autenticazione per Azure usando il Azure CLI. Quando l'app viene eseguita, nell'output vengono visualizzate le voci pertinenti seguenti:

[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

Nell'output precedente è possibile notare quanto segue:

• EnvironmentCredential, WorkloadIdentityCredential, ManagedIdentityCredential, IntelliJCredential e VisualStudioCodeCredential non sono riusciti ad acquisire un token di accesso Microsoft Entra, in tale ordine.
• La AzureCliCredential.getToken chiamata ha esito positivo, come indicato dall'elemento returns a token-suffisso. Poiché AzureCliCredential ha avuto successo, non sono state provate ulteriori credenziali.