Catene di credenziali nella libreria client di Identità di Azure per C++

La libreria client di Identità di Azure fornisce le credenziali, ovvero tipi pubblici che derivano dalla classe di base astratta 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 possono essere concatenate 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 correttamente un token di accesso. 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 esso, è necessario scrivere codice simile al seguente:

  // Set up credential based on environment (Azure or local development)
  std::shared_ptr<Azure::Core::Credentials::TokenCredential> credential;
  if (std::getenv("WEBSITE_HOSTNAME"))
  {
      credential = std::make_shared<Azure::Identity::ManagedIdentityCredential>();
  }
  else
  {
      credential = std::make_shared<Azure::Identity::AzureCliCredential>();
  }
  

• 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

Con C++, sono disponibili due opzioni per il concatenamento delle credenziali:

• Usare una catena preconfigurata: usare la catena preconfigurata implementata dal tipo di DefaultAzureCredential. Per questo approccio, consultare la sezione panoramica di DefaultAzureCredential.
• Creare una catena di credenziali personalizzata: iniziare con 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. La progettazione supporta molti ambienti, insieme ai flussi di autenticazione e agli strumenti di sviluppo più comuni. In forma grafica, la catena sottostante è simile alla seguente:

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

Ordinamento	Credenziali di accesso	Descrizione
1	Ambiente	Legge una raccolta di variabili di ambiente per determinare se un'entità servizio dell'applicazione (utente dell'applicazione) sia configurata per l'applicazione. In tal 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.
2	Identità del carico di lavoro	Se l'app è distribuita in un host di Azure con Identità di Workload abilitata, autentica l'account.
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.
4	Interfaccia della riga di comando di Azure	Se lo sviluppatore si è autenticato su Azure utilizzando il comando az login dell'Azure CLI, autentica l'app in Azure usando lo stesso account.

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

#include <azure/identity/default_azure_credential.hpp>
#include <azure/storage/blobs/blob_client.hpp>

int main()
{
    // create a credential
    auto credential = std::make_shared<Azure::Identity::DefaultAzureCredential>();

    // create a Blob service client
    auto blobUrl = "https://<my_account_name>.blob.core.windows.net/mycontainer/myblob";
    Azure::Storage::Blobs::BlobClient blobClient{blobUrl, credential};
}

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 utilizzato un valore di dev, la catena include solo AzureCliCredential.

Per assicurarsi che la variabile di ambiente sia definita e impostata su una stringa supportata, passare true al DefaultAzureCredential costruttore:

auto credential = std::make_shared<Azure::Identity::DefaultAzureCredential>(true);

Importante

Il sovraccarico del costruttore sopracitato è supportato nelle versioni del pacchetto azure-identity-cpp 1.13.1 e successive.

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
• EnvironmentCredential
• ManagedIdentityCredential
• WorkloadIdentityCredential

Per assicurarsi che la variabile di ambiente sia definita e impostata su una stringa supportata, passare true al DefaultAzureCredential costruttore:

auto credential = std::make_shared<Azure::Identity::DefaultAzureCredential>(true);

Importante

Il sovraccarico del costruttore sopracitato è supportato nelle versioni del pacchetto azure-identity-cpp 1.13.1 e successive.

Panoramica di ChainedTokenCredential

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

#include <azure/identity/azure_cli_credential.hpp>
#include <azure/identity/chained_token_credential.hpp>
#include <azure/identity/managed_identity_credential.hpp>
#include <azure/storage/blobs/blob_client.hpp>

int main()
{
    // create a credential
    auto credential = std::make_shared<Azure::Identity::ChainedTokenCredential>(
        Azure::Identity::ChainedTokenCredential::Sources{
            std::make_shared<Azure::Identity::ManagedIdentityCredential>(),
            std::make_shared<Azure::Identity::AzureCliCredential>()});

    // create a Blob service client
    auto blobUrl = "https://<my_account_name>.blob.core.windows.net/mycontainer/myblob";
    Azure::Storage::Blobs::BlobClient blobClient{blobUrl, credential};
}

L'esempio di codice precedente crea una catena di credenziali personalizzata costituita da due credenziali. Si tenta ManagedIdentityCredential per primo, seguito da AzureCliCredential, se necessario. In forma grafica, la catena è simile alla seguente:

Suggerimento

Per migliorare le prestazioni, ottimizzare l'ordinamento delle credenziali in ChainedTokenCredential dalla credenziale più a quella meno usata.

Indicazioni sull'utilizzo per DefaultAzureCredential

DefaultAzureCredential è senza dubbio il modo più semplice per iniziare a usare la libreria client di Identità di Azure, ma con tale praticità si verifica un compromesso. Dopo aver distribuito 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.

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 l'avanzamento da una credenziale alla successiva e lo stato di esito positivo/negativo di ognuno di essi. 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, quando viene eseguito su una macchina di sviluppo locale, l'identità gestita non è disponibile. Di conseguenza, ManagedIdentityCredential ha sempre esito negativo nell'ambiente di sviluppo locale.
• 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. A scopo illustrativo, si supponga che venga usata la forma senza parametri di DefaultAzureCredential per autenticare una richiesta a un account di archiviazione BLOB. L'app viene eseguita nell'ambiente di sviluppo locale e lo sviluppatore ha eseguito l'autenticazione in Azure usando l'interfaccia della riga di comando di Azure. Quando l'app viene eseguita, nell'output vengono visualizzate le voci pertinenti seguenti:

DEBUG : Identity: Creating DefaultAzureCredential which combines multiple parameterless credentials into a single one.
DefaultAzureCredential is only recommended for the early stages of development, and not for usage in production environment.
Once the developer focuses on the Credentials and Authentication aspects of their application, DefaultAzureCredential needs to be replaced with the credential that is the better fit for the application.
INFO  : Identity: EnvironmentCredential gets created with ClientSecretCredential.
DEBUG : Identity: EnvironmentCredential: 'AZURE_TENANT_ID', 'AZURE_CLIENT_ID', and 'AZURE_CLIENT_SECRET' environment variables are set, so ClientSecretCredential with corresponding tenantId, clientId, and clientSecret gets created.
WARN  : Identity: Azure Kubernetes environment is not set up for the WorkloadIdentityCredential credential to work.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with App Service 2019 source.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with App Service 2017 source.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with Cloud Shell source.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with Azure Arc source.
INFO  : Identity: ManagedIdentityCredential will be created with Azure Instance Metadata Service source.
Successful creation does not guarantee further successful token retrieval.
INFO  : Identity: AzureCliCredential created.
Successful creation does not guarantee further successful token retrieval.
INFO  : Identity: DefaultAzureCredential: Created with the following credentials: EnvironmentCredential, WorkloadIdentityCredential, ManagedIdentityCredential, AzureCliCredential.
DEBUG : Identity: DefaultAzureCredential: Failed to get token from EnvironmentCredential: GetToken(): error response: 400 Bad Request

{"error":"invalid_grant","error_description":"AADSTS53003: Access has been blocked by Conditional Access policies. The access policy does not allow token issuance. Trace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333 Correlation ID: aaaa0000-bb11-2222-33cc-444444dddddd Timestamp: 2025-03-07 21:25:44Z","error_codes":[53003],"timestamp":"2025-03-07 21:25:44Z","trace_id":"0000aaaa-11bb-cccc-dd22-eeeeee333333","correlation_id":"aaaa0000-bb11-2222-33cc-444444dddddd","error_uri":"https://login.microsoftonline.com/error?code=53003","suberror":"message_only","claims":"{\"access_token\":{\"capolids\":{\"essential\":true,\"values\":[\"cccc2222-dd33-4444-55ee-666666ffffff\"]}}}"}
WARN  : Identity: WorkloadIdentityCredential authentication unavailable. See earlier WorkloadIdentityCredential log messages for details.
DEBUG : Identity: DefaultAzureCredential: Failed to get token from WorkloadIdentityCredential: WorkloadIdentityCredential authentication unavailable. Azure Kubernetes environment is not set up correctly.
INFO  : Identity: DefaultAzureCredential: Successfully got token from ManagedIdentityCredential. This credential will be reused for subsequent calls.
DEBUG : Identity: DefaultAzureCredential: Saved this credential at index 2 for subsequent calls.

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.
• ManagedIdentityCredential ha esito positivo, come indicato da un record che inizia con "Successfully got token from ManagedIdentityCredential".