Chaînes d’informations d’identification dans la bibliothèque Azure Identity pour .NET
La bibliothèque Azure Identity fournit des informations d’identification (des classes publiques dérivées de la classe TokenCredential de la bibliothèque Azure Core). Les informations d’identification représentent un flux d’authentification distinct pour l’acquisition d’un jeton d’accès à partir de l’ID Microsoft Entra. 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’informations d’identification
Les informations d’identification chaînées 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 :
TokenCredential credential; if (app.Environment.IsProduction() || app.Environment.IsStaging()) { credential = new ManagedIdentityCredential(clientId: userAssignedClientId); } else { // local development environment credential = new VisualStudioCredential(); }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 des informations d’identification chaînées
Il existe deux philosophies différentes pour le chaînage des informations d’identification :
- « Démonter » une chaîne : commencez par une chaîne préconfigurée et excluez ce dont vous n’avez pas besoin. Pour cette approche, consultez la section Présentation de DefaultAzureCredential.
- « Créer » une chaîne : commencez par une chaîne vide et incluez uniquement ce dont vous avez besoin. Pour cette approche, consultez la section Présentation de ChainedTokenCredential.
Présentation de DefaultAzureCredential
"DefaultAzureCredential est une chaîne d’informations d’identification préconfigurée et stricte. Elle est conçue pour prendre 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.
| Ordre | Informations d'identification | Description | Activée par défaut ? |
|---|---|---|---|
| 1 | Environment | 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. |
Oui |
| 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. | Oui |
| 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. | Oui |
| 4 | Visual Studio | Si le développeur s’est authentifié auprès d’Azure en se connectant à Visual Studio, authentifiez l’application auprès d’Azure en utilisant ce même compte. | Oui |
| 5 | 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. |
Oui |
| 6 | Azure PowerShell | Si le développeur s’est authentifié auprès d’Azure à l’aide de l’applet de commande Connect-AzAccount d'Azure PowerShell, authentifiez l’application auprès d’Azure en utilisant ce même compte. |
Oui |
| 7 | Azure Developer CLI | Si le développeur s’est authentifié auprès d’Azure à l’aide de la commande azd auth login d'Azure Developer CLI, authentifiez-vous avec ce compte. |
Oui |
| 8 | Navigateur interactif | Si cette option est activée, authentifiez le développeur de manière interactive via le navigateur par défaut du système actuel. | Non |
Dans sa forme la plus simple, vous pouvez utiliser la version sans paramètre de DefaultAzureCredential comme suit :
builder.Services.AddAzureClients(clientBuilder =>
{
clientBuilder.AddBlobServiceClient(
new Uri("https://<account-name>.blob.core.windows.net"));
DefaultAzureCredential credential = new();
clientBuilder.UseCredential(credential);
});
Conseil
La UseCredential méthode de l’extrait de code précédent est recommandée pour une utilisation dans les applications ASP.NET Core. Pour plus d’informations, consultez Utiliser le Kit de développement logiciel (SDK) Azure pour .NET dans les applications ASP.NET Core.
Comment personnaliser DefaultAzureCredential
Pour supprimer des informations d’identification de DefaultAzureCredential, utilisez la propriété correspondante précédée du préfixe Exclude dans DefaultAzureCredentialOptions. Par exemple :
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,
}));
});
Dans l’exemple de code précédent, EnvironmentCredential et WorkloadIdentityCredential sont supprimés de la chaîne d’informations d’identification. Par conséquent, les premières informations d’identification à tenter sont ManagedIdentityCredential. La chaîne modifiée ressemble à ceci :
Remarque
InteractiveBrowserCredential est exclu par défaut et n’est donc pas affiché dans le diagramme précédent. Pour inclure InteractiveBrowserCredential, passez true au constructeur DefaultAzureCredential(Boolean) ou définissez la propriété DefaultAzureCredentialOptions.ExcludeInteractiveBrowserCredential sur false.
À mesure que d’autres propriétés précédées du préfixe Exclude sont définies sur true (les exclusions d’informations d’identification sont configurées), les avantages de l’utilisation de DefaultAzureCredential diminuent. Dans ce cas, ChainedTokenCredential est un meilleur choix et nécessite moins de code. Pour illustrer ceci, ces deux exemples de code se comportent de la même façon :
credential = new DefaultAzureCredential(
new DefaultAzureCredentialOptions
{
ExcludeEnvironmentCredential = true,
ExcludeWorkloadIdentityCredential = true,
ExcludeAzureCliCredential = true,
ExcludeAzurePowerShellCredential = true,
ExcludeAzureDeveloperCliCredential = true,
ManagedIdentityClientId = userAssignedClientId
});
Présentation 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 :
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’exemple de code précédent crée une chaîne d’informations d’identification personnalisée composée de deux informations d’identification. La variante d’identité managée de ManagedIdentityCredential affectée par l’utilisateur est tentée en premier, suivie de VisualStudioCredential, si nécessaire. Sous forme graphique, la chaîne ressemble à ceci :
Conseil
Pour améliorer les performances, optimisez l’ordre des informations d’identification dans ChainedTokenCredential pour votre environnement de production. Les informations d’identification destinées à être utilisées dans l’environnement de développement local doivent être ajoutées en dernier.
Conseils d’utilisation pour DefaultAzureCredential
DefaultAzureCredential est sans aucun doute le moyen le plus simple de commencer avec la bibliothèque Azure Identity, mais cette commodité s'accompagne de 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, vous devez sérieusement envisager de passer de DefaultAzureCredential à l’une des solutions suivantes :
- Une implémentation de
TokenCredentialspécifique, telle queManagedIdentityCredential. Consultez la liste Dérivé pour plus d'options. - Une implémentation de
ChainedTokenCredentialsimplifiée et optimisée pour l’environnement Azure dans lequel votre application s’exécute.
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 la journalisation pour voir la progression d’une information d’identification à l’autre et l’état de réussite/échec de chacun d’entre elles. Pour plus d’informations, consultez Déboguer des informations d’identification chaînées.
- 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. Par conséquent,
ManagedIdentityCredentialéchoue toujours dans l’environnement de développement local, sauf si elle est explicitement désactivée via sa propriété correspondante précédée du préfixeExclude. - Comportement imprévisible :
DefaultAzureCredentialvé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 deDefaultAzureCredentialau 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. Si vous le souhaitez, filtrez les journaux uniquement sur les événements émis à partir de la bibliothèque Azure Identity. Par exemple :
using AzureEventSourceListener listener = new((args, message) =>
{
if (args is { EventSource.Name: "Azure-Identity" })
{
Console.WriteLine(message);
}
}, EventLevel.LogAlways);
À des fins d’illustration, supposons que la forme sans paramètre de DefaultAzureCredential été utilisée pour authentifier une demande auprès d’un espace de travail analytique des journaux d'activité. L’application s’est exécutée dans l’environnement de développement local et Visual Studio a été authentifié sur un compte Azure. Lors de l'exécution suivante de l’application, les entrées pertinentes suivantes sont apparues dans la sortie :
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
Dans la sortie précédente, vous pouvez voir que :
EnvironmentCredential,WorkloadIdentityCredentialetManagedIdentityCredentialn’ont pas pu acquérir un jeton d’accès Microsoft Entra, dans cet ordre.- L’entrée précédée du préfixe
DefaultAzureCredential credential selected:indique les informations d’identification sélectionnées (VisualStudioCredentialdans ce cas). La tentative avecVisualStudioCredentialayant réussi, aucune autre information d’identification n’a été utilisée.
