Chaînes d’informations d’identification dans la bibliothèque de client Azure Identity pour C++

La bibliothèque cliente Azure Identity fournit des informations d’identification ( types publics dérivés de la classe de base abstraite TokenCredential de la bibliothèque Azure Core). Un justificatif d'identité représente un processus d'authentification distinct pour acquérir un jeton d'accès depuis Microsoft Entra ID. Ces informations d’identification peuvent être chaînées pour former une séquence ordonnée de mécanismes d’authentification à essayer.

Fonctionnement des informations d’identification chaînées

Au moment de l’exécution, une chaîne d’informations d’identification tente de s’authentifier à l’aide des premières informations d’identification de la séquence. Si ces informations d’identification ne parviennent pas à acquérir un jeton d’accès, les informations d’identification suivantes de la séquence sont utilisées, et ainsi de suite jusqu’à l’obtention d’un jeton d’accès. Le diagramme de séquence suivant illustre ce comportement.

Pourquoi utiliser des chaînes d'identifiants ?

Les certificats d'authentification chaînés peuvent offrir les avantages suivants :

• Prise en compte de l’environnement : sélectionne automatiquement les informations d’identification les plus appropriées en fonction de l’environnement dans lequel l’application s’exécute. Sans cela, vous devrez écrire du code comme suit :

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

• Fluidité des transitions : votre application peut passer du développement local à votre environnement de préproduction ou de production sans modifier le code d’authentification.

• Amélioration de la résilience : inclut un mécanisme de secours qui passe aux informations d’identification suivantes lorsque le précédent ne parvient pas à acquérir un jeton d’accès.

Comment choisir un identifiant chaîné

Avec C++, il existe deux choix pour le chaînage des informations d’identification :

• Utiliser une chaîne préconfigurée: utilisez la chaîne préconfigurée implémentée par le type de DefaultAzureCredential. Pour cette approche, consultez la section Présentation de DefaultAzureCredential.
• Créer une chaîne d’informations d’identification personnalisée: commencez par une chaîne vide et incluez uniquement ce dont vous avez besoin. Pour cette approche, consultez la section Présentation de ChainedTokenCredential.

Vue d’ensemble de DefaultAzureCredential

DefaultAzureCredential est une chaîne d’informations d’identification préconfigurée et stricte. Sa conception prend en charge de nombreux environnements, ainsi que les flux d’authentification et les outils de développement les plus courants. Sous forme graphique, la chaîne sous-jacente ressemble à ceci :

L'ordre dans lequel DefaultAzureCredential tente les informations d’identification est le suivant.

JSON	Informations d'identification	Descriptif
1	Environnement	Lit une collection de variables d’environnement pour déterminer si un principal de service d’application (utilisateur d’application) est configuré pour l’application. Si c’est le cas, DefaultAzureCredential utilise ces valeurs pour authentifier l’application auprès d’Azure. Cette méthode est le plus souvent utilisée dans les environnements serveur, mais peut également être utilisée lors du développement local.
2	Identité de charge de travail	Si l’application est déployée sur un hôte Azure avec Workload Identity activé, authentifiez ce compte.
3	Identité gérée	Si l’application est déployée sur un hôte Azure avec l’identité managée activée, authentifiez l'application auprès d'Azure en utilisant cette identité managée.
4	Azure CLI	Si le développeur s’est authentifié auprès d’Azure à l’aide de la commande az login d'Azure CLI, authentifiez l’application auprès d’Azure en utilisant ce même compte.

Dans sa forme la plus simple, vous pouvez utiliser la version sans paramètre de DefaultAzureCredential comme suit :

#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};
}

Comment personnaliser DefaultAzureCredential

Les sections suivantes décrivent les stratégies de contrôle des informations d’identification incluses dans la chaîne.

Exclure une catégorie de type d’informations d’identification

Pour exclure toutes les informations d'identification de type Developer tool ou Deployed service, définissez la variable d'environnement AZURE_TOKEN_CREDENTIALS sur prod ou dev, respectivement. Lorsqu’une valeur est prod utilisée, la chaîne d’informations d’identification sous-jacente se présente comme suit :

Lorsqu'une valeur de dev est utilisée, la chaîne n'inclut que AzureCliCredential.

Pour vous assurer que la variable d’environnement est définie et assignée à une chaîne prise en charge, passez true au constructeur DefaultAzureCredential.

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

Importante

La surcharge de constructeur mentionnée ci-dessus est prise en charge dans les versions de package 1.13.1 et ultérieures de azure-identity-cpp.

Utiliser des informations d’identification spécifiques

Pour exclure toutes les informations d’identification à l’exception d’une, définissez la variable AZURE_TOKEN_CREDENTIALS d’environnement sur le nom des informations d’identification. Par exemple, vous pouvez réduire la DefaultAzureCredential chaîne en AzureCliCredential définissant AZURE_TOKEN_CREDENTIALS sur AzureCliCredential. La comparaison de chaînes est effectuée de manière non sensible à la casse. Les valeurs de chaîne valides pour la variable d’environnement sont les suivantes :

• AzureCliCredential
• EnvironmentCredential
• ManagedIdentityCredential
• WorkloadIdentityCredential

Pour vous assurer que la variable d’environnement est définie et assignée à une chaîne prise en charge, passez true au constructeur DefaultAzureCredential.

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

Importante

La surcharge de constructeur mentionnée ci-dessus est prise en charge dans les versions de package 1.13.1 et ultérieures de azure-identity-cpp.

Vue d’ensemble de ChainedTokenCredential

ChainedTokenCredential est une chaîne vide à laquelle vous ajoutez des informations d’identification pour répondre aux besoins de votre application. Par exemple:

#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’exemple de code précédent crée une chaîne d’informations d’identification personnalisée composée de deux informations d’identification. ManagedIdentityCredential est tentée en premier, suivie de AzureCliCredential, si nécessaire. Sous forme graphique, la chaîne ressemble à ceci :

Conseil / Astuce

Pour améliorer les performances, optimisez l’ordre des informations d’identification dans ChainedTokenCredential de la plupart aux informations d’identification les moins utilisées.

Conseils d’utilisation pour DefaultAzureCredential

DefaultAzureCredential est sans aucun doute le moyen le plus simple de commencer avec la bibliothèque de client Azure Identity, mais avec cette commodité vient les compromis. Une fois que vous avez déployé votre application sur Azure, vous devez comprendre les exigences d’authentification de l’application. Pour cette raison, remplacez DefaultAzureCredential par une implémentation de TokenCredential spécifique, telle que ManagedIdentityCredential.

Voici pourquoi :

• Problèmes de débogage : en cas d’échec de l’authentification, il peut être difficile de déboguer et d’identifier les informations d’identification incriminées. Vous devez activer l'enregistrement pour voir la progression d'un justificatif d'identité à l'autre et l'état de réussite/échec de chacun. Pour plus d’informations, consultez Déboguer des identifiants chaînés.
• Surcharge des performances : le processus de tentative séquentielle de plusieurs informations d’identification peut introduire une surcharge de performances. Par exemple, lors de l’exécution sur un ordinateur de développement local, l’identité managée n’est pas disponible. En conséquence, ManagedIdentityCredential échoue toujours dans l’environnement de développement local.
• Comportement imprévisible : DefaultAzureCredential vérifie la présence de certaines variables d’environnement. Il est possible que quelqu’un puisse ajouter ou modifier ces variables d’environnement au niveau du système sur l’ordinateur hôte. Ces modifications s’appliquent globalement et modifient donc le comportement de DefaultAzureCredential au moment de l’exécution dans n’importe quelle application s’exécutant sur cet ordinateur.

Déboguer des informations d’identification chaînées

Pour diagnostiquer un problème inattendu ou comprendre ce que font les informations d’identification chaînées, activez la journalisation dans votre application. À des fins d’illustration, supposons que la forme sans paramètre de DefaultAzureCredential soit utilisée pour authentifier une requête à un compte Blob Storage. L’application s’exécute dans l’environnement de développement local, et le développeur s’est authentifié sur Azure à l’aide de l’Azure CLI. Lorsque l’application est exécutée, les entrées pertinentes suivantes apparaissent dans la sortie :

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.

Dans la sortie précédente, vous pouvez voir que :

• EnvironmentCredential, WorkloadIdentityCredential et ManagedIdentityCredential n’ont pas pu acquérir un jeton d’accès Microsoft Entra, dans cet ordre.
• ManagedIdentityCredential réussit, comme indiqué par une entrée commençant par «Successfully got token from ManagedIdentityCredential ».