Bibliothèque de client d’authentification des applications pour .NET - version 1.6.0

  • Article

Notes

Microsoft.Azure.Services.AppAuthentication a été mis hors service et n’est plus pris en charge ou géré. Elle est remplacée par la bibliothèque de client Azure Identity disponible pour .NET, Java, TypeScript et Python. Vous trouverez des informations sur la migration Azure Identityici : Azure Identity.

Pour vous authentifier auprès des services Azure avec un principal de service, vous avez besoin d’informations d’identification Azure Active Directory (Azure AD), soit d’un secret partagé, soit d’un certificat.

La gestion de ces informations d’identification peut être difficile. Il peut être tentant de regrouper les informations d’identification au sein d’une application, en les incluant dans des fichiers source ou de configuration. L’élément Microsoft.Azure.Services.AppAuthentication de la bibliothèque .NET simplifie ce problème. Il utilise les informations d’identification du développeur pour l’authentification pendant le développement local. Lorsque la solution est déployée ultérieurement vers Azure, la bibliothèque bascule automatiquement vers les informations d’identification de l’application. Il est plus sûr d’utiliser les informations d’identification du développeur pendant le développement local, car vous n’avez pas besoin de créer des informations d’identification Azure AD ou de partager des informations d’identification entre les développeurs.

La bibliothèque Microsoft.Azure.Services.AppAuthentication gère l’authentification automatiquement, ce qui vous permet de vous concentrer sur votre solution, plutôt que sur vos informations d’identification. Elle prend en charge le développement local avec Microsoft Visual Studio, Azure CLI ou l’authentification intégrée Azure AD. Quand elle est déployée sur une ressource Azure qui prend en charge une identité managée, la bibliothèque utilise automatiquement des identités managées pour les ressources Azure. Aucune modification du code ou de la configuration n’est requise. La bibliothèque prend également en charge les informations d’identification client Azure AD lorsqu’une identité managée n’est pas disponible, ou lorsque le contexte de sécurité du développeur ne peut être déterminé pendant le développement local.

| Code sourcePackage (nuget) | Documentation Azure Active Directory

Prérequis

  • Visual Studio 2019 ou Visual Studio 2017 v15.5.

  • L’extension d’authentification d’application pour Visual Studio, disponible en tant qu’extension distincte de Visual Studio 2017 Update 5, et regroupée avec le produit dans Update 6 et versions ultérieures. Avec Update 6 ou ultérieure, vous pouvez vérifier l’installation de l’extension d’authentification d’application en sélectionnant les outils de développement Azure dans le programme d’installation de Visual Studio.

Utilisation de la bibliothèque

Pour les applications .NET, la façon la plus simple d’utiliser une identité managée consiste à tirer parti du package Microsoft.Azure.Services.AppAuthentication. Voici comment démarrer :

  1. Sélectionnez Outils>Gestionnaire de package NuGet>Gérer les packages NuGet pour la solution pour ajouter des références aux packages NuGet Microsoft.Azure.Services.AppAuthentication et Microsoft.Azure.KeyVault pour votre projet.

  2. Utilisez AzureServiceTokenProvider pour simplifier la demande de jetons d’accès pour vos clients Azure, comme dans les exemples ci-dessous :

    using Microsoft.Azure.Services.AppAuthentication;
using Microsoft.Azure.KeyVault;
using System.Data.SqlClient

// Use AzureServiceTokenProvider’s built-in callback for KeyVaultClient
var azureServiceTokenProvider = new AzureServiceTokenProvider();
var kv = new KeyVaultClient(new KeyVaultClient.AuthenticationCallback(azureServiceTokenProvider.KeyVaultTokenCallback));

// Request an access token for SqlConnection
sqlConnection = new SqlConnection(YourConnectionString)) 
{ 
    sqlConnection.AccessToken = await azureServiceTokenProvider.GetAccessTokenAsync("https://database.windows.net"); 
    sqlConnection.Open(); 
}

La classe AzureServiceTokenProvider thread-safe met en cache le jeton en mémoire et le récupère auprès d’Azure AD, juste avant l’expiration. Cela signifie que vous n’avez jamais besoin de vérifier l’expiration du jeton avant d’appeler la méthode GetAccessTokenAsync.

La méthode GetAccessTokenAsync requiert un identificateur de ressource. Pour en savoir plus sur services Microsoft Azure, voirQue sont les identités managées pour les ressources Azure ?.

Authentification du développement local

Pour un développement local, il existe deux scénarios d’authentification principaux : authentification auprès des services Azure et authentification auprès des services personnalisés.

Authentification auprès des services Azure

Les ordinateurs locaux ne prennent pas en charge les identités managées pour les ressources Azure. Par conséquent, la bibliothèque Microsoft.Azure.Services.AppAuthentication utilise vos informations d’identification de développeur pour s’exécuter dans votre environnement de développement local. Lorsque la solution est déployée sur Azure, la bibliothèque utilise une identité managée pour basculer vers un flux d’octroi d’informations d’identification de client OAuth 2.0. Cette approche signifie que vous pouvez sans problème tester le même code en local et à distance.

Pour le développement local, AzureServiceTokenProvider extrait des jetons à l’aide de Visual Studio, de l’interface de ligne de commande Azure (CLI) ou de l’authentification intégrée Azure AD. Le système essaie chaque option de manière séquentielle et utilise la première option qui aboutit. Si aucune option ne fonctionne, une exception AzureServiceTokenProviderException est levée, avec des informations détaillées.

Authentification avec Visual Studio

Pour authentifier à l’aide de Visual Studio :

  1. Connectez-vous à Visual Studio puis sélectionnez Outils>Options pour ouvrir Options.

  2. Sélectionnez Authentification par le service Azure, choisissez un compte pour le développement local, puis cliquez sur OK.

Si vous rencontrez des problèmes lorsque vous utilisez Visual Studio, telles que les erreurs impliquant le fichier du fournisseur de jetons, lisez attentivement les étapes précédentes.

Il se peut que vous deviez authentifier à nouveau votre jeton de développeur. Pour ce faire, sélectionnez Options d’outils>, puis Sélectionnez Authentification du service Azure. Recherchez un lien Réauthentifier sous le compte sélectionné. Cliquez sur ce lien pour effectuer l’authentification.

Authentification avec Azure CLI

Pour utiliser Azure CLI pour le développement local, vérifiez que vous disposez d’Azure CLI v 2.0.12 ou version ultérieure.

Pour utiliser Azure CLI :

  1. Recherchez Azure CLI dans la barre des tâches Windows pour ouvrir l’invite de commandes de Microsoft Azure.

  2. Connectez-vous au portail Azure : az login pour se connecter à Azure.

  3. Vérifiez l’accès en entrant az account get-access-token --resource https://vault.azure.net. Si vous recevez une erreur, vérifiez que la version appropriée d’Azure CLI est correctement installée.

    Si Azure CLI n’est pas installé dans le répertoire par défaut, vous pouvez recevoir une erreur signalant que AzureServiceTokenProvider ne peut pas trouver le chemin d’accès à Azure CLI. Utilisez la variable d’environnement AzureCLIPath pour définir le dossier d’installation d’Azure CLI. Le paramètre AzureServiceTokenProvider ajoute le répertoire spécifié dans la variable d’environnement AzureCLIPath à la variable d’environnement Path, le cas échéant.

  4. Si vous êtes connecté à Azure CLI à l’aide de plusieurs comptes, ou si votre compte peut accéder à plusieurs abonnements, vous devez spécifier l’abonnement à utiliser. Entrez la commande az account set --subscription .

Cette commande génère une sortie uniquement en cas d’échec. Pour vérifier les paramètres de compte en cours, entrez la commande az account list.

Authentification via la fonction d’authentification Azure AD

Pour utiliser l’authentification Azure Active Directory, vérifiez les éléments suivants :

Authentification auprès de services personnalisés

Lorsqu’un service appelle les services Azure, les étapes précédentes sont applicables, car ces services permettent d’accéder aux utilisateurs et aux applications.

Lorsque vous créez un service qui appelle un service personnalisé, utilisez les informations d’identification du client Azure AD pour l’authentification de développement local. Nous avons deux options :

  • Utilisez un principal de service pour la connexion à Azure :

    1. Créer un principal de service. Pour plus d’informations, consultez Créer un principal de service Azure avec Azure CLI.

    2. Utilisez Azure CLI pour vous connecter avec la commande suivante :

      az login --service-principal -u <principal-id> --password <password> --tenant <tenant-id> --allow-no-subscriptions

      Comme le principal du service ne dispose pas nécessairement d’un accès à un abonnement, utilisez l’argument --allow-no-subscriptions.

  • Utilisez des variables d’environnement pour spécifier les détails du principal de service. Pour en savoir plus, voir Exécution de l’application à l’aide d’un principal de service.

Une fois que vous êtes connecté à Azure, AzureServiceTokenProvider récupère un jeton pour le développement local à l’aide du principal de service.

Cette approche s’applique uniquement au développement local. Lorsque votre solution est déployée sur Azure, la bibliothèque bascule sur une identité managée pour l’authentification.

Exécution de l’application en utilisant une identité managée ou une identité affectée par l’utilisateur

Lorsque vous exécutez votre code dans Azure App Service ou une machine virtuelle Azure pour laquelle une identité managée est activée, la bibliothèque utilise automatiquement l’identité managée. Aucune modification du code n’est requise, mais l’identité managée doit disposer d’autorisations pour les ressources auxquelles elle tentera d’accéder. Par exemple, des stratégies d’accès sont requises pour qu’une identité managée accède aux secrets d’un coffre de clés.

Vous pouvez aussi authentifier avec une identité affectée par l’utilisateur. Pour en savoir plus sur les identités affectées par l’utilisateur, consultez À propos des identités managées pour les ressources Azure. Pour s’authentifier avec une identité affectée à l’utilisateur, vous devez spécifier l’ID client dans la chaîne de connexion. La chaîne de connexion est spécifiée dans Prise en charge de chaînes de connexion.

Exécution de l’application à l’aide d’un principal de service

Il peut être nécessaire de créer une information d’identification de client Azure Active Directory pour s’authentifier. Cette situation peut se produire dans les exemples suivants :

  • Votre code s’exécute dans un environnement de développement local, mais non sous l’identité du développeur. Service Fabric, par exemple, utilise le compte NetworkService pour le développement local.

  • Votre code s’exécute dans un environnement de développement local, et vous êtes authentifié auprès d’un service personnalisé. Vous n’utilisez donc pas votre identité de développeur.

  • Votre code s’exécute sur une ressource de calcul Azure qui ne prend pas encore en charge les identités managées pour les ressources Azure, comme Azure Batch.

Il existe trois méthodes principales d’utilisation d’un principal de service pour exécuter votre application. Pour utiliser un d’eux, vous devez d’abord créer un principal de service. Pour plus d’informations, consultez Créer un principal de service Azure avec Azure CLI.

Utilisez un certificat dans le magasin de clés local pour vous connecter à Azure AD

  1. Créer un certificat principal de service à l’aide de la commande Azure CLI az ad sp create-for-rbac.

    az ad sp create-for-rbac --create-cert

    Cette commande crée un fichier .pem (clé privée) qui est stocké dans votre répertoire de base. Convertissez le fichier .pem en certificat PFX à l’aide de la commande :

    openssl pkcs12 -export -in test.pem -out test.pfx

  2. Définissez la variable d’environnement AzureServicesAuthConnectionString sur la valeur suivante :

    RunAs=App;AppId={AppId};TenantId={TenantId};CertificateThumbprint={Thumbprint};
      CertificateStoreLocation={CertificateStore}

    Remplacez {AppId} , {TenantId} et {Thumbprint} par les valeurs générées à l’étape 1. Remplacez {CertificateStore} par LocalMachine ou CurrentUser, en fonction de votre plan de déploiement.

  3. Exécutez l'application.

Utilisez une information d’identification de secret partagé pour vous connecter à Azure AD

  1. Créez un certificat principal de service avec un mot de passe à l’aide de la commande Azure CLI az ad sp create-for-rbac et du paramètre --sdk-auth.

    az ad sp create-for-rbac --sdk-auth

  2. Définissez la variable d’environnement AzureServicesAuthConnectionString sur la valeur suivante :

    RunAs=App;AppId={AppId};TenantId={TenantId};AppKey={ClientSecret}

    Remplacez {AppId} , {TenantId} et {ClientSecret} par les valeurs générées à l’étape 1.

  3. Exécutez l'application.

Une fois les systèmes correctement configurés, le code n’a pas besoin d’être modifié plus avant. AzureServiceTokenProvider utilise la variable d’environnement et le certificat pour l’authentification auprès d’Azure AD.

Utilisez un certificat dans Key Vault pour vous connecter à Azure AD

Cette option vous permet de stocker le certificat de client d’un principal de service dans Key Vault et l’utiliser pour l’authentification de principal de service. Vous pouvez utiliser cette option pour les scénarios suivants :

  • Authentification locale, dans laquelle vous souhaitez vous authentifier à l’aide d’un principal de service explicite et que vous souhaitez conserver les informations d’identification du principal de service en toute sécurité dans un coffre de clés. Compte de développeur doit avoir accès au coffre de clés.

  • Authentification à partir d’Azure où vous souhaitez utiliser les informations d’identification explicites et pour conserver les informations d’identification du principal de service en toute sécurité dans un coffre de clés. Vous pouvez utiliser cette option pour un scénario interlocataire. Identité managée doit avoir accès au coffre de clés.

L’identité managée ou votre identité de développeur doit avoir l’autorisation de récupérer le certificat de client à partir du coffre de clés. La bibliothèque AppAuthentication utilise le certificat récupéré comme informations d’identification du client du principal de service.

Pour utiliser un certificat client pour l’authentification de principal de service :

  1. Créez un certificat de principal du service et stockez-le automatiquement dans votre Key Vault. Utilisez la commande Azure CLI az ad sp create-for-rbac --keyvault keyvaultname <> --cert <certificatename> --create-cert --skip-assignment :

    az ad sp create-for-rbac --keyvault <keyvaultname> --cert <certificatename> --create-cert --skip-assignment

    L’identificateur de certificat sera une URL au format https://<keyvaultname>.vault.azure.net/secrets/<certificatename>

  2. Remplacez {KeyVaultCertificateSecretIdentifier} dans cette chaîne de connexion avec l’identificateur de certificat :

    RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier={KeyVaultCertificateSecretIdentifier}

    Par exemple, si votre coffre de clés a été appelé myKeyVault et que vous avez créé un certificat nommé myCert, l’identificateur de certificat serait :

    RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier=https://myKeyVault.vault.azure.net/secrets/myCert

Prise en charge de chaînes de connexion

Par défaut, AzureServiceTokenProvider essaie les méthodes d’authentification suivantes, dans l’ordre, pour récupérer un jeton :

Pour contrôler le processus, utilisez une chaîne de connexion passée au constructeur AzureServiceTokenProvider ou spécifiée dans la variable d’environnement AzureServicesAuthConnectionString. Les options suivantes sont prises en charge :

Option de chaîne de connexion Scénario Commentaires
RunAs=Developer;DeveloperTool=AzureCli Développement local AzureServiceTokenProvider utilise Azure CLI pour obtenir un jeton.
RunAs=Developer;DeveloperTool=VisualStudio Développement local AzureServiceTokenProvider utilise Visual Studio pour obtenir un jeton.
RunAs=CurrentUser Développement local Non pris en charge dans .NET Core. AzureServiceTokenProvider utilise l’authentification intégrée Azure AD pour obtenir un jeton.
RunAs=App Identités managées pour les ressources Azure AzureServiceTokenProvider utilise une identité managée pour obtenir in jeton.
RunAs=App;AppId={ClientId of user-assigned identity} Identité affectée par l’utilisateur pour les ressources Azure AzureServiceTokenProvider utilise une identité affectée par l’utilisateur pour obtenir un jeton.
RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier={KeyVaultCertificateSecretIdentifier} Authentification des services personnalisés KeyVaultCertificateSecretIdentifier est l’identificateur du secret du certificat.
RunAs=App;AppId={AppId};TenantId={TenantId};CertificateThumbprint={Thumbprint};CertificateStoreLocation={LocalMachine or CurrentUser} Principal du service AzureServiceTokenProvider utilise un certificat pour obtenir un jeton de la part d’Azure AD.
RunAs=App;AppId={AppId};TenantId={TenantId};CertificateSubjectName={Subject};CertificateStoreLocation={LocalMachine or CurrentUser} Principal du service AzureServiceTokenProvider utilise un certificat pour obtenir un jeton de la part d’Azure AD.
RunAs=App;AppId={AppId};TenantId={TenantId};AppKey={ClientSecret} Principal du service AzureServiceTokenProvider utilise un secret pour obtenir un jeton de la part d’Azure AD.

Exemples

Pour voir la bibliothèque Microsoft.Azure.Services.AppAuthentication en action, voir les exemples de code suivant.

Résolution des problèmes AppAuthentication

Problèmes courants lors du développement local

Azure CLI n’est pas installé, vous n’êtes pas connecté ou vous ne disposez pas de la dernière version

Exécutez az account get-access-token pour déterminer si Azure CLI affiche un jeton pour vous. Si aucun programme de ce type n’est trouvé, installez la dernière version d’Azure CLI. Vous serez peut-être invité à vous connecter.

AzureServiceTokenProvider ne peut pas trouver le chemin d’accès pour Azure CLI

AzureServiceTokenProvider recherche Azure CLI à ses emplacements d’installation par défaut. S’il ne trouve pas Azure CLI, définissez la variable d’environnement AzureCLIPath sur le dossier d’installation Azure CLI. AzureServiceTokenProvider ajoute la variable d’environnement à la variable d’environnement de chemin.

Vous êtes connecté à Azure CLI à l’aide de plusieurs comptes, le même compte a accès aux abonnements dans plusieurs locataires, ou vous recevez une erreur d’accès refusé lorsque vous essayez d’effectuer des appels pendant le développement local

À l’aide d’Azure CLI, définissez l’abonnement par défaut sur celui qui contient le compte que vous souhaitez utiliser. L’abonnement doit être dans le même locataire que la ressource à laquelle vous souhaitez accéder : az account set --subscription [subscription-id] . Si aucune sortie n’est visible, cela signifie que la procédure a réussi. Vérifiez que le compte approprié est désormais le compte par défaut à l’aide de la commande az account list.

Problèmes courants dans les environnements

Accès non autorisé, accès refusé, interdit, ou erreur similaire

Le principal utilisé n’a pas accès à la ressource à laquelle il tente d’accéder. Accordez à votre compte d’utilisateur ou au « contributeur » MSI d’App Service l’accès à une ressource. Celle-ci varie selon que vous exécutez l’exemple sur votre ordinateur local ou déployé dans Azure sur votre App Service. Certaines ressources, telles que les coffres de clés, disposent également de leurs propres stratégies d’accès que vous pouvez utiliser pour accorder l’accès aux principaux (utilisateurs, applications et groupes).

Problèmes courants lors du déploiement sur Azure App Service

L’identité gérée n’est pas configurée sur l’App Service

Vérifiez que les variables d’environnement MSI_ENDPOINT et MSI_SECRET existent à l’aide de la console de débogage Kudu. Si ces variables d’environnement n’existent pas, l’identité managée n’est pas activée sur le App Service.

Problèmes courants lors du déploiement local avec IIS

Impossible de récupérer les jetons lors du débogage de l’application dans IIS

Par défaut, AppAuth s’exécute dans un contexte utilisateur différent dans IIS. C’est pourquoi il n’a pas accès à l’utilisation de votre identité de développeur pour récupérer des jetons d’accès. Vous pouvez configurer IIS pour qu’il s’exécute avec votre contexte utilisateur en suivant les deux étapes suivantes :

  • Configurez le pool d’applications pour que l’application Web s’exécute en tant que compte d’utilisateur actuel. Plus d’informations, cliquez ici

  • Configurez « setProfileEnvironment » sur « true ». Plus d’informations, cliquez ici.

    • Accédez à %windir%\System32\inetsrv\config\applicationHost.config
    • Recherchez « setProfileEnvironment ». Si la valeur est définie sur « false », modifiez-la en « true ». S’il n’est pas présent, ajoutez-le en tant qu’attribut à l’élément processModel (/configuration/system.applicationHost/applicationPools/applicationPoolDefaults/processModel/@setProfileEnvironment), puis définissez-le sur « True ».

  • En savoir plus sur les identités managées pour les ressources Azure.

  • Apprenez-en davantage sur les scénarios d’authentification Azure AD.