Catene di credenziali nella libreria di identità di Azure per .NET

La libreria di identità di Azure Identity offre delle credenziali, classi pubbliche derivate dalla classe TokenCredential della libreria di 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:

  TokenCredential credential;
  
  if (app.Environment.IsProduction() || app.Environment.IsStaging())
  {
      credential = new ManagedIdentityCredential(
          ManagedIdentityId.FromUserAssignedClientId(userAssignedClientId));
  }
  else
  {
      // local development environment
      credential = new VisualStudioCredential();
  }
  

• Transizioni lineari: l'app può passare dall'ambiente di sviluppo locale a quello di gestione temporanea o di produzione senza modificare il codice l'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 filosofie diverse per il concatenamento delle credenziali:

• "Disinstallare" una catena: iniziare da una catena preconfigurata ed escludere ciò che non serve. Per questo approccio, vedere 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 vincolante. È 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.

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

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddSecretClient(
        new Uri($"https://{keyVaultName}.vault.azure.net"));
    clientBuilder.AddBlobServiceClient(
        new Uri($"https://{storageAccountName}.blob.core.windows.net"));
});

Come personalizzare DefaultAzureCredential

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

Escludere una singola credenziale

Per escludere una singola credenziale da DefaultAzureCredential, utilizzare la proprietà corrispondente con prefisso Exclude in DefaultAzureCredentialOptions. Ad esempio:

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddSecretClient(
        new Uri($"https://{keyVaultName}.vault.azure.net"));
    clientBuilder.AddBlobServiceClient(
        new Uri($"https://{storageAccountName}.blob.core.windows.net"));

    clientBuilder.UseCredential(new DefaultAzureCredential(
        new DefaultAzureCredentialOptions
        {
            ExcludeEnvironmentCredential = true,
            ExcludeManagedIdentityCredential = true,
            ExcludeWorkloadIdentityCredential = true,
        }));
});

Nell'esempio di codice precedente, EnvironmentCredential, ManagedIdentityCredentiale WorkloadIdentityCredential vengono rimossi dalla catena di credenziali. Di conseguenza, la prima credenziale da tentare è VisualStudioCredential. La catena modificata contiene solo le credenziali in fase di sviluppo e ha un aspetto simile al seguente:

Man mano che aumentano le proprietà con prefisso Exclude impostate su true (le esclusioni di credenziali sono configurate) diminuiscono i vantaggi dell'utilizzo di DefaultAzureCredential. In questi casi, ChainedTokenCredential è una scelta migliore e richiede meno codice. Per un esempio, questi due codici si comportano allo stesso modo:

credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        ExcludeEnvironmentCredential = true,
        ExcludeWorkloadIdentityCredential = true,
        ExcludeManagedIdentityCredential = true,
        ExcludeVisualStudioCodeCredential = true,
        ExcludeAzurePowerShellCredential = true,
        ExcludeAzureDeveloperCliCredential = true,
        ExcludeBrokerCredential = true,
    });

credential = new ChainedTokenCredential(
    new VisualStudioCredential(),
    new AzureCliCredential());

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, usare l'overload DefaultAzureCredential(String, DefaultAzureCredentialOptions)del costruttore .

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 DefaultAzureCredential catena a VisualStudioCredential impostando AZURE_TOKEN_CREDENTIALS su VisualStudioCredential. 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
• BrokerCredential
• EnvironmentCredential
• InteractiveBrowserCredential
• ManagedIdentityCredential
• VisualStudioCredential
• VisualStudioCodeCredential
• WorkloadIdentityCredential

Per assicurarsi che la variabile di ambiente sia definita e impostata su una stringa supportata, usare l'overload DefaultAzureCredential(String, DefaultAzureCredentialOptions)del costruttore .

Panoramica di ChainedTokenCredential

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

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddSecretClient(
        new Uri($"https://{keyVaultName}.vault.azure.net"));
    clientBuilder.AddBlobServiceClient(
        new Uri($"https://{storageAccountName}.blob.core.windows.net"));

    clientBuilder.UseCredential(new ChainedTokenCredential(
        new AzurePowerShellCredential(),
        new VisualStudioCredential()));
});

L'esempio di codice precedente crea una catena di credenziali personalizzata costituita da due credenziali in fase di sviluppo. Si tenta AzurePowerShellCredential per primo, seguito da VisualStudioCredential, 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à di Azure, ma questa facilità comporta anche degli svantaggi. Una volta distribuita l'app in Azure, è necessario comprendere i requisiti di autenticazione dell'app. Per questo motivo, sostituire DefaultAzureCredential con un'implementazione di TokenCredential specifica, ad esempio ManagedIdentityCredential. Vedere l'elenco Derivato per le opzioni.

Ecco perché:

• 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.
• Overhead delle prestazioni: il processo di prova sequenziale di più credenziali può introdurre l'overhead 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, a meno che non sia disabilitato in modo esplicito tramite la proprietà con prefisso Exclude corrispondente.
• Comportamento imprevedibile: DefaultAzureCredential verifica la presenza di alcune variabili di 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. Per altre informazioni sull'imprevedibilità, vedere Usare credenziali deterministiche negli ambienti di produzione.

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. Facoltativamente, filtrare i log per visualizzare solo gli eventi generati dalla libreria di identità di Azure. Ad esempio:

using AzureEventSourceListener listener = new((args, message) =>
{
    if (args is { EventSource.Name: "Azure-Identity" })
    {
        Console.WriteLine(message);
    }
}, EventLevel.LogAlways);

A scopo illustrativo, supponiamo che sia stata usata la forma senza parametri di DefaultAzureCredential per autenticare una richiesta a un'area di lavoro Log Analytics. L'app è stata eseguita nell'ambiente di sviluppo locale e Visual Studio è stato autenticato in un account Azure. Alla successiva esecuzione dell'app, nell'output compaiono le seguenti voci pertinenti:

DefaultAzureCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
EnvironmentCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
EnvironmentCredential.GetToken was unable to retrieve an access token. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 Exception: Azure.Identity.CredentialUnavailableException (0x80131500): EnvironmentCredential authentication unavailable. Environment variables are not fully configured. See the troubleshooting guide for more information. https://aka.ms/azsdk/net/identity/environmentcredential/troubleshoot
WorkloadIdentityCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
WorkloadIdentityCredential.GetToken was unable to retrieve an access token. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 Exception: Azure.Identity.CredentialUnavailableException (0x80131500): WorkloadIdentityCredential authentication unavailable. The workload options are not fully configured. See the troubleshooting guide for more information. https://aka.ms/azsdk/net/identity/workloadidentitycredential/troubleshoot
ManagedIdentityCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
ManagedIdentityCredential.GetToken was unable to retrieve an access token. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 Exception: Azure.Identity.CredentialUnavailableException (0x80131500): ManagedIdentityCredential authentication unavailable. No response received from the managed identity endpoint.
VisualStudioCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
VisualStudioCredential.GetToken succeeded. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 ExpiresOn: 2024-08-13T17:16:50.8023621+00:00
DefaultAzureCredential credential selected: Azure.Identity.VisualStudioCredential
DefaultAzureCredential.GetToken succeeded. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 ExpiresOn: 2024-08-13T17:16:50.8023621+00:00

Nell'output precedente è possibile notare quanto segue:

• EnvironmentCredential, WorkloadIdentityCredential e ManagedIdentityCredential hanno tutte fallito nel tentativo di acquisire un token di accesso Microsoft Entra, nell'ordine.
• La voce con prefisso DefaultAzureCredential credential selected: indica la credenziale selezionata,VisualStudioCredential in questo caso. Dato che VisualStudioCredential è riuscita nell'intento, non sono state usate altre credenziali.