Bibliothèque de client Azure Identity pour .NET - version 1.10.3

La bibliothèque d’identités Azure fournit la prise en charge de l’authentification par jeton d’ID Microsoft Entra (anciennement Azure Active Directory) dans l’ensemble du Kit de développement logiciel (SDK) Azure. Il fournit un ensemble d’implémentations TokenCredential qui peuvent être utilisées pour construire des clients du Kit de développement logiciel (SDK) Azure qui prennent en charge l’authentification par jeton Microsoft Entra.

| Code sourcePackage (NuGet) | Documentation de référence sur les | APIdocumentation sur l’ID Microsoft Entra

Prise en main

Installer le package

Installez la bibliothèque de client Azure Identity pour .NET avec NuGet :

dotnet add package Azure.Identity

Prérequis

• Un abonnement Azure.
• Azure CLI peut également être utile pour l’authentification dans un environnement de développement, la création de comptes et la gestion des rôles de compte.

Authentifier le client

Lors du débogage et de l’exécution de code localement, il est courant pour un développeur d’utiliser son propre compte pour authentifier les appels aux services Azure. Il existe plusieurs outils de développement qui peuvent servir à cette authentification dans votre environnement de développement.

S’authentifier via Visual Studio

Les développeurs utilisant Visual Studio 2017 ou version ultérieure peuvent authentifier un compte Microsoft Entra via l’IDE. Les applications utilisant les DefaultAzureCredential ou VisualStudioCredential peuvent ensuite utiliser ce compte pour authentifier les appels dans le cadre d’une exécution locale.

Pour vous authentifier dans Visual Studio, sélectionnez le menu Options des outils> pour lancer la boîte de dialogue Options. Accédez ensuite aux Azure Service Authentication options pour vous connecter avec votre compte Microsoft Entra.

S’authentifier via Visual Studio Code

Les développeurs qui utilisent Visual Studio Code peuvent utiliser l’extension de compte Azure pour s’authentifier via l’éditeur. Les applications utilisant les DefaultAzureCredential ou VisualStudioCodeCredential peuvent ensuite utiliser ce compte pour authentifier les appels dans le cadre d’une exécution locale.

Il s’agit d’un problème connu qui VisualStudioCodeCredential ne fonctionne pas avec les versions d’extension de compte Azure plus récentes que 0.9.11. Une solution à long terme à ce problème est en cours. En attendant, envisagez de vous authentifier via Azure CLI.

S’authentifier via Azure CLI

Les développeurs qui codent en dehors d’un IDE peuvent également utiliser Azure CLI pour s’authentifier. Les applications utilisant les DefaultAzureCredential ou AzureCliCredential peuvent ensuite utiliser ce compte pour authentifier les appels dans le cadre d’une exécution locale.

Pour s’authentifier avec Azure CLI, les utilisateurs peuvent exécuter la commande az login. Pour les utilisateurs s’exécutant sur un système avec un navigateur web par défaut, Azure CLI lance le navigateur pour authentifier l’utilisateur.

Sur les systèmes sans navigateur web par défaut, la commande az login utilise le flux d’authentification de code d’appareil. L’utilisateur peut également spécifier l’argument --use-device-code pour forcer Azure CLI à utiliser le flux de code d’appareil au lieu de lancer un navigateur.

S’authentifier via le Azure Developer CLI

Les développeurs qui codent en dehors d’un IDE peuvent également utiliser les Azure Developer CLI pour s’authentifier. Les applications utilisant les DefaultAzureCredential ou AzureDeveloperCliCredential peuvent ensuite utiliser ce compte pour authentifier les appels dans le cadre d’une exécution locale.

Pour s’authentifier avec le Azure Developer CLI, les utilisateurs peuvent exécuter la commande azd auth login. Pour les utilisateurs s’exécutant sur un système avec un navigateur web par défaut, le Azure Developer CLI lance le navigateur pour authentifier l’utilisateur.

Sur les systèmes sans navigateur web par défaut, la commande azd auth login --use-device-code utilise le flux d’authentification de code d’appareil.

S’authentifier via Azure PowerShell

Les développeurs qui codent en dehors d’un IDE peuvent également utiliser Azure PowerShell pour s’authentifier. Les applications utilisant les DefaultAzureCredential ou AzurePowerShellCredential peuvent ensuite utiliser ce compte pour authentifier les appels dans le cadre d’une exécution locale.

Pour s’authentifier avec Azure PowerShell, les utilisateurs peuvent exécuter la commande Connect-AzAccount. Pour les utilisateurs s’exécutant sur un système avec un navigateur web par défaut et la version 5.0.0 ou ultérieure d’Azure PowerShell, le navigateur est lancé pour authentifier l’utilisateur.

Sur les systèmes sans navigateur web par défaut, la commande Connect-AzAccount utilise le flux d’authentification de code d’appareil. L’utilisateur peut également forcer Azure PowerShell à utiliser le flux de code de l’appareil au lieu de lancer un navigateur en spécifiant l’argument UseDeviceAuthentication .

Concepts clés

Informations d'identification

Les informations d’identification sont une classe qui contient ou peut obtenir les données nécessaires à un client de service pour authentifier les demandes. Les clients de service dans le Kit de développement logiciel (SDK) Azure acceptent les informations d’identification lorsqu’ils sont construits. Les clients de service utilisent ces informations d’identification pour authentifier les demandes adressées au service.

La bibliothèque d’identités Azure se concentre sur l’authentification OAuth avec Microsoft Entra ID et offre diverses classes d’informations d’identification capables d’acquérir un jeton Microsoft Entra pour authentifier les demandes de service. Toutes les classes d’informations d’identification de cette bibliothèque sont des implémentations de la TokenCredential classe abstraite dans Azure.Core, et chacune d’entre elles peut être utilisée pour construire des clients de service capables de s’authentifier avec un TokenCredential.

Pour obtenir la liste complète des types d’informations d’identification disponibles, consultez Classes d’informations d’identification.

DefaultAzureCredential

Convient à la DefaultAzureCredential plupart des scénarios où l’application est destinée à être exécutée dans Azure. C’est parce que les DefaultAzureCredential combinent les informations d’identification couramment utilisées pour l’authentification lors du déploiement avec les informations d’identification utilisées pour l’authentification dans un environnement de développement.

Remarque : DefaultAzureCredential est destiné à simplifier la prise en main du Kit de développement logiciel (SDK) en gérant des scénarios courants avec des comportements par défaut raisonnables. Les développeurs qui souhaitent davantage de contrôle ou dont le scénario n’est pas pris en charge par les paramètres par défaut doivent utiliser d’autres types d’informations d’identification.

Les DefaultAzureCredential essaient l’authentification via les mécanismes suivants, dans l’ordre indiqué, et s’arrêtent dès que l’un de ces derniers s’avère concluant :

1. Environnement : lit les DefaultAzureCredential informations de compte spécifiées via des variables d’environnement et les utilise pour s’authentifier.
2. Identité de charge de travail : si l’application est déployée sur un hôte Azure avec l’identité de charge de travail activée, le DefaultAzureCredential s’authentifie avec ce compte.
3. Identité managée : si l’application est déployée sur un hôte Azure avec l’identité managée activée, le DefaultAzureCredential s’authentifie avec ce compte.
4. Visual Studio : si le développeur s’est authentifié via Visual Studio, le DefaultAzureCredential s’authentifie avec ce compte.
5. Visual Studio Code : actuellement exclu par défaut comme l’authentification sdk via Visual Studio Code est interrompue en raison du problème #27263. Le VisualStudioCodeCredential est réactivé dans le flux une fois qu’un DefaultAzureCredential correctif est en place. Le problème n° 30525 suit ce problème. En attendant, les utilisateurs de Visual Studio Code peuvent authentifier leur environnement de développement à l’aide d’Azure CLI.
6. Azure CLI : si le développeur a authentifié un compte via la commande Azure CLI az login , s’authentifie DefaultAzureCredential auprès de ce compte.
7. Azure PowerShell : si le développeur a authentifié un compte via la commande Azure PowerShellConnect-AzAccount, s’authentifie auprès de DefaultAzureCredential ce compte.
8. Azure Developer CLI : si le développeur s’est authentifié via la commande Azure Developer CLIazd auth login, s’authentifie auprès de DefaultAzureCredential ce compte.
9. Navigateur interactif - Si cette option est activée, les DefaultAzureCredential authentifient le développeur de manière interactive via le navigateur par défaut du système actuel. Par défaut, ce type d’informations d’identification est désactivé.

Stratégie de continuation

À partir de la version 1.10.1, DefaultAzureCredential tente de s’authentifier avec toutes les informations d’identification du développeur jusqu’à ce que l’une d’elles réussisse, quelles que soient les erreurs que les informations d’identification du développeur précédentes ont rencontrées. Par exemple, une information d’identification de développeur peut tenter d’obtenir un jeton et échouer. Elle passe donc DefaultAzureCredential aux informations d’identification suivantes dans le flux. Les informations d’identification de service déployées arrêtent le flux avec une exception levée si elles sont en mesure de tenter de récupérer des jetons, mais qu’elles n’en reçoivent pas. Avant la version 1.10.1, les informations d’identification du développeur arrêtaient de la même façon le flux d’authentification en cas d’échec de la récupération de jeton.

Ce comportement permet d’essayer toutes les informations d’identification du développeur sur votre ordinateur tout en ayant un comportement de déploiement prévisible.

Exemples

Authentifier avec DefaultAzureCredential

Cet exemple illustre l’authentification du SecretClient à partir de la bibliothèque de client Azure.Security.KeyVault.Secrets à l’aide de DefaultAzureCredential.

// Create a secret client using the DefaultAzureCredential
var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), new DefaultAzureCredential());

Activer l’authentification interactive avec DefaultAzureCredential

L’authentification interactive est désactivée dans le DefaultAzureCredential par défaut. Cet exemple montre deux façons d’activer la partie d’authentification interactive de .DefaultAzureCredential Lorsqu’il est activé DefaultAzureCredential , le revient à l’authentification interactive du développeur via le navigateur par défaut du système si aucune autre information d’identification n’est disponible. Cet exemple authentifie ensuite un à EventHubProducerClient partir de la bibliothèque de client Azure.Messaging.EventHubs à l’aide de avec l’authentification DefaultAzureCredential interactive activée.

// the includeInteractiveCredentials constructor parameter can be used to enable interactive authentication
var credential = new DefaultAzureCredential(includeInteractiveCredentials: true);

var eventHubClient = new EventHubProducerClient("myeventhub.eventhubs.windows.net", "myhubpath", credential);

Spécifier une identité managée affectée par l’utilisateur avec DefaultAzureCredential

De nombreux hôtes Azure autorisent l’attribution d’une identité managée affectée par l’utilisateur. Cet exemple illustre la configuration de DefaultAzureCredential pour authentifier une identité affectée par l’utilisateur lors du déploiement sur un hôte Azure. Il authentifie ensuite un BlobClient à partir de la bibliothèque de client Azure.Storage.Blobs avec des informations d’identification.

// When deployed to an azure host, the default azure credential will authenticate the specified user assigned managed identity.

string userAssignedClientId = "<your managed identity client Id>";
var credential = new DefaultAzureCredential(new DefaultAzureCredentialOptions { ManagedIdentityClientId = userAssignedClientId });

var blobClient = new BlobClient(new Uri("https://myaccount.blob.core.windows.net/mycontainer/myblob"), credential);

En plus de configurer via le ManagedIdentityClientId code, il peut également être défini à l’aide de la variable d’environnement AZURE_CLIENT_ID . Ces deux approches sont équivalentes lors de l’utilisation de DefaultAzureCredential.

Définir un flux d’authentification personnalisé avec des ChainedTokenCredential

L’utilisation des DefaultAzureCredential est généralement le moyen le plus rapide pour commencer à développer des applications pour Azure, mais les utilisateurs plus expérimentés souhaiteront peut-être personnaliser les informations d’identification prises en compte lors de l’authentification. Avec ChainedTokenCredential, les utilisateurs peuvent combiner plusieurs instances d’informations d’identification pour définir une chaîne d’informations d’identification personnalisée. Cet exemple illustre la création d’un ChainedTokenCredential qui tente de s’authentifier à l’aide d’une identité managée et de revenir à l’authentification via Azure CLI si l’identité managée n’est pas disponible dans l’environnement actuel. Les informations d’identification sont ensuite utilisées pour authentifier un EventHubProducerClient à partir de la bibliothèque de client Azure.Messaging.EventHubs.

// Authenticate using managed identity if it is available; otherwise use the Azure CLI to authenticate.

var credential = new ChainedTokenCredential(new ManagedIdentityCredential(), new AzureCliCredential());

var eventHubProducerClient = new EventHubProducerClient("myeventhub.eventhubs.windows.net", "myhubpath", credential);

Prise en charge des identités managées

L’authentification d’identité managée est prise en charge via ou DefaultAzureCredentialManagedIdentityCredential directement pour les services Azure suivants :

• Azure App Service et Azure Functions
• Azure Arc
• Azure Cloud Shell
• Azure Kubernetes Service
• Azure Service Fabric
• Machines virtuelles Azure
• Azure Virtual Machine Scale Sets

Exemples

Ces exemples illustrent l’authentification du SecretClient à partir de la bibliothèque cliente Azure.Security.KeyVault.Secrets à l’aide de ManagedIdentityCredential.

S’authentifier avec une identité managée affectée par l’utilisateur

var credential = new ManagedIdentityCredential(clientId: userAssignedClientId);
var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), credential);

S’authentifier avec une identité managée affectée par le système

var credential = new ManagedIdentityCredential();
var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), credential);

Cloud configuration

Par défaut, les informations d’identification s’authentifient auprès du point de terminaison Microsoft Entra pour le cloud public Azure. Pour accéder aux ressources dans d’autres clouds, telles que Azure Government ou un cloud privé, configurez les informations d’identification avec l’argument AuthorityHost . AzureAuthorityHosts définit les autorités pour les clouds connus :

var credential = new DefaultAzureCredential(new DefaultAzureCredentialOptions { AuthorityHost = AzureAuthorityHosts.AzureGovernment });

Toutes les informations d’identification ne nécessitent pas cette configuration. Les informations d’identification qui s’authentifient via un outil de développement, tel que AzureCliCredential, utilisent la configuration de cet outil.

Classes d’informations d’identification

Authentifier les applications hébergées par Azure

Authentifier les principaux de service

Authentification des utilisateurs

S’authentifier via des outils de développement

Note: Toutes les implémentations d’informations d’identification dans la bibliothèque Azure Identity sont threadsafe et une seule instance d’informations d’identification peut être utilisée par plusieurs clients de service.

Variables d'environnement

Les DefaultAzureCredential et EnvironmentCredential peuvent être configurés à l’aide de variables d’environnement. Chaque type d’authentification nécessite des valeurs pour des variables spécifiques :

Principal de service avec une clé secrète

Principal de service avec un certificat

Nom d’utilisateur et mot de passe

La configuration est tentée dans l’ordre indiqué ci-dessus. Par exemple, si les valeurs d’un certificat et d’une clé secrète client sont toutes deux présentes, la clé secrète client est utilisée.

Évaluation continue de l’accès

À partir de la version 1.10.0, l’accès aux ressources protégées par l’évaluation continue de l’accès (CAE) est possible par demande. Ce comportement peut être activé en définissant la IsCaeEnabled propriété de TokenRequestContext via son constructeur. CAE n’est pas pris en charge pour les informations d’identification de développeur et d’identité managée.

Mise en cache de jeton

La mise en cache de jetons est une fonctionnalité fournie par la bibliothèque Azure Identity qui permet aux applications de :

• Cachez les jetons en mémoire (par défaut) ou sur le disque (opt-in).
• Améliorez la résilience et les performances.
• Réduisez le nombre de demandes adressées à Microsoft Entra ID pour obtenir des jetons d’accès.

La bibliothèque Azure Identity offre à la fois une mise en cache de disque en mémoire et persistante. Pour plus d’informations, consultez la documentation relative à la mise en cache des jetons

Dépannage

Consultez le guide de résolution des problèmes pour plus d’informations sur la façon de diagnostiquer différents scénarios d’échec.

Gestion des erreurs

Les erreurs résultant de l’authentification peuvent être générées sur n’importe quelle méthode cliente de service qui effectue une demande au service. Cela est dû au fait que la première fois que le jeton est demandé à partir des informations d’identification se trouve sur le premier appel au service et que les appels suivants peuvent avoir besoin d’actualiser le jeton. Pour distinguer ces échecs des échecs dans le client de service, les classes Azure Identity soulèvent le AuthenticationFailedException avec les détails de la source de l’erreur dans le message d’exception, ainsi que éventuellement le message d’erreur. Selon l’application, ces erreurs peuvent ou non être récupérables.

using Azure.Identity;
using Azure.Security.KeyVault.Secrets;

// Create a secret client using the DefaultAzureCredential
var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), new DefaultAzureCredential());

try
{
    KeyVaultSecret secret = await client.GetSecretAsync("secret1");
}
catch (AuthenticationFailedException e)
{
    Console.WriteLine($"Authentication Failed. {e.Message}");
}

Pour plus d’informations sur la gestion des erreurs liées à l’échec de demandes adressées à Microsoft Entra ID ou aux points de terminaison d’identité managée, consultez la documentation relative aux id de Microsoft Entra sur les codes d’erreur d’autorisation.

Journalisation

La bibliothèque Azure Identity fournit les mêmes fonctionnalités de journalisation que le reste du Kit de développement logiciel (SDK) Azure.

Le moyen le plus simple de voir les journaux pour aider à déboguer les problèmes d’authentification consiste à activer la journalisation de la console.

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

Toutes les informations d’identification peuvent être configurées avec des options de diagnostic, de la même manière que d’autres clients dans le SDK.

ATTENTION: Les demandes et réponses dans la bibliothèque Azure Identity contiennent des informations sensibles. Des précautions doivent être prises pour protéger les journaux, lors de la personnalisation de la sortie, afin d’éviter de compromettre la sécurité du compte.

DefaultAzureCredentialOptions options = new DefaultAzureCredentialOptions
{
    Diagnostics =
    {
        LoggedHeaderNames = { "x-ms-request-id" },
        LoggedQueryParameters = { "api-version" },
        IsLoggingContentEnabled = true
    }
};

Lorsque vous résolvez les problèmes d’authentification, vous pouvez également activer la journalisation des informations sensibles. Pour activer ce type de journalisation, définissez la propriété sur IsLoggingContentEnabledtrue. Pour journaliser uniquement les détails du compte utilisé pour tenter d’authentification et d’autorisation, définissez IsAccountIdentifierLoggingEnabled sur true.

DefaultAzureCredentialOptions options = new DefaultAzureCredentialOptions
{
    Diagnostics =
    {
        LoggedHeaderNames = { "x-ms-request-id" },
        LoggedQueryParameters = { "api-version" },
        IsAccountIdentifierLoggingEnabled = true
    }
};

Sécurité des threads

Nous garantissons que toutes les méthodes d’informations d’identification instance sont thread-safe et indépendantes les unes des autres (recommandations). Cela garantit que la recommandation de réutilisation des instances d’informations d’identification est toujours sécurisée, même entre les threads.

Concepts supplémentaires

Options clientes | Accès à la réponse | Diagnostics | Moqueur | Durée de vie du client

Étapes suivantes

Bibliothèques clientes prenant en charge l’authentification avec Azure Identity

La plupart des bibliothèques clientes répertoriées ici prennent en charge l’authentification avec TokenCredential et la bibliothèque d’identités Azure. Vous y trouverez également des liens où vous pouvez en savoir plus sur leur utilisation, y compris une documentation et des exemples supplémentaires.

Problèmes connus

Cette bibliothèque ne prend actuellement pas en charge les scénarios relatifs au service Azure AD B2C .

Les problèmes ouverts pour la Azure.Identity bibliothèque sont disponibles ici.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez https://cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.