Condividi tramite

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

  • Articolo

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:

Diagramma di sequenza della catena di credenziali

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(clientId: 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:

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:

Diagramma di flusso dell'autenticazione DefaultAzureCredential

L'ordine in cui DefaultAzureCredential tenta le credenziali.

Ordinamento Credenziale Descrizione Abilitata per impostazione predefinita?
1 Ambiente Legge una raccolta di variabili di ambiente per determinare se un'entità servizio applicazione (utente applicazione) è configurata per l'app. In questo caso, DefaultAzureCredential usa questi valori per autenticare l'app in Azure. Questo metodo viene usato più spesso negli ambienti server, ma può essere usato anche durante lo sviluppo in locale. Sì
2 Identità del carico di lavoro Se l'app viene distribuita in un host di Azure con identità del carico di lavoro abilitata, autenticare l'account. Sì
3 Identità gestita Se l'app viene distribuita in un host di Azure con identità gestita abilitata, autentica l'app in Azure usando l'identità gestita. Sì
4 Visual Studio Se lo sviluppatore ha eseguito l'autenticazione in Azure accedendo a Visual Studio, autenticare l'app in Azure usando lo stesso account. Sì
5 Interfaccia della riga di comando di Azure Se lo sviluppatore ha eseguito l'autenticazione in Azure usando il comando az login dell'interfaccia della riga di comando, autenticare l'app in Azure usando lo stesso account. Sì
6 Azure PowerShell Se lo sviluppatore ha eseguito l'autenticazione in Azure usando il cmdlet Connect-AzAccount di PowerShell, autenticare l'app in Azure usando lo stesso account. Sì
7 Azure Developer CLI Se lo sviluppatore ha eseguito l'autenticazione in Azure usando il comando azd auth login dell'interfaccia a riga di comando di Azure Developer, eseguire l'autenticazione con tale account. Sì
8 Browser interattivo Se abilitato, autenticare in modo interattivo lo sviluppatore tramite il browser predefinito del sistema corrente. No

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

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddBlobServiceClient(
        new Uri("https://<account-name>.blob.core.windows.net"));

    DefaultAzureCredential credential = new();
    clientBuilder.UseCredential(credential);
});

Suggerimento

Il UseCredential metodo nel frammento di codice precedente è consigliato per l'uso nelle app ASP.NET Core. Per altre informazioni, vedere Usare Azure SDK per .NET nelle app ASP.NET Core.

Come personalizzare DefaultAzureCredential

Per rimuovere una credenziale da DefaultAzureCredential, usare la proprietà corrispondente con prefisso Exclude in DefaultAzureCredentialOptions. Ad esempio:

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddBlobServiceClient(
        new Uri("https://<account-name>.blob.core.windows.net"));

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

Nell'esempio di codice precedente, EnvironmentCredential e WorkloadIdentityCredential vengono rimossi dalla catena di credenziali. Di conseguenza, la prima credenziale da tentare è ManagedIdentityCredential. La catena modificata ha un aspetto simile alla seguente:

DefaultAzureCredential con le proprietà Excludes

Nota

InteractiveBrowserCredential viene esclusa per impostazione predefinita, pertanto non compare nel diagramma precedente. Per includere InteractiveBrowserCredential, passare true al costruttore DefaultAzureCredential(Boolean) o impostare la proprietà DefaultAzureCredentialOptions.ExcludeInteractiveBrowserCredential su false.

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,
        ExcludeAzureCliCredential = true,
        ExcludeAzurePowerShellCredential = true,
        ExcludeAzureDeveloperCliCredential = true,
        ManagedIdentityClientId = userAssignedClientId
    });

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.AddBlobServiceClient(
        new Uri("https://<account-name>.blob.core.windows.net"));

    clientBuilder.UseCredential(new ChainedTokenCredential(
        new ManagedIdentityCredential(clientId: userAssignedClientId),
        new VisualStudioCredential()));
});

L'esempio di codice precedente crea una catena di credenziali personalizzata che ne comprende due. La variante con identità gestita assegnata dall'utente di ManagedIdentityCredential viene tentata per prima, seguita da VisualStudioCredential, se necessario. Graficamente, la catena è simile alla seguente:

ChainedTokenCredential

Suggerimento

Per migliorare le prestazioni, ottimizzare l'ordinamento delle credenziali in ChainedTokenCredential per l'ambiente di produzione. Le credenziali destinate all'uso nell'ambiente di sviluppo locale devono essere aggiunte per ultime.

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 è consigliabile passare da DefaultAzureCredential a una delle soluzioni seguenti:

  • Una specifica implementazione di TokenCredential, ad esempio ManagedIdentityCredential. Vedere l'elenco Derivato per le opzioni.
  • Un'implementazione essenziale di ChainedTokenCredential ottimizzata per l'ambiente Azure in cui viene eseguita l'app.

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.

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.