Démarrage rapide : Appeler une API web ASP.NET qui est protégée par la plateforme d’identités Microsoft

Le démarrage rapide suivant utilise un exemple de code qui démontre comment protéger une API Web ASP.NET en limitant l’accès à ses ressources aux seuls comptes autorisés. L’exemple prend en charge l’autorisation des comptes Microsoft personnels et des comptes dans n’importe quelle organisation Microsoft Entra.

L’article utilise également une application Windows Presentation Foundation (WPF) pour montrer comment demander un jeton d’accès afin d’accéder à une API web.

Prérequis

• Compte Azure avec un abonnement actif. Créez un compte gratuitement.
• Visual Studio 2022. Téléchargez Visual Studio gratuitement.

Cloner ou télécharger l’exemple

L’exemple de code peut être obtenu de deux manières :

• Le cloner à partir de votre interpréteur de commandes ou de votre ligne de commande :

  git clone https://github.com/AzureADQuickStarts/AppModelv2-NativeClient-DotNet.git
  

• Le télécharger sous la forme d’un fichier Zip.

Conseil

Pour éviter les erreurs dues à des limitations de longueur de chemin dans Windows, nous vous recommandons d’extraire l’archive ou de cloner le référentiel dans un répertoire près de la racine de votre lecteur.

Inscrire l’API web (TodoListService)

Conseil

Les étapes décrites dans cet article peuvent varier légèrement en fonction du portail de départ.

Inscrivez votre API web dans Inscriptions d’applications au sein du portail Azure.

1. Connectez-vous au Centre d’administration de Microsoft Entra au minimum en tant qu’Administrateur d’application cloud.

2. Si vous avez accès à plusieurs tenants, utilisez l’icône Paramètres dans le menu supérieur pour basculer vers le tenant dans lequel vous voulez inscrire l’application à partir du menu Répertoires + abonnements.

3. Accédez à Identité>Applications>Inscriptions d’applications, puis sélectionnez Nouvelle inscription.

4. Entrez un nom pour votre application (par exemple, AppModelv2-NativeClient-DotNet-TodoListService). Les utilisateurs de votre application peuvent voir ce nom, et vous pouvez le changer ultérieurement.

5. Pour Types de comptes pris en charge, sélectionnez Comptes dans un annuaire organisationnel.

6. Sélectionnez Inscrire pour créer l’application.

7. Dans la page Vue d’ensemble de l’application, recherchez la valeur ID d’application (client) , puis notez-la pour une utilisation ultérieure. Vous en avez besoin pour configurer le fichier de configuration Visual Studio pour ce projet (autrement dit ClientId dans le fichier TodoListService\appsettings.json).

8. Sous Gérer, sélectionnez Exposer une API>Ajouter une étendue. Acceptez l’URI d’ID d’application proposé (api://{clientId}) en sélectionnant Enregistrer et continuer, puis entrez les informations suivantes :

   1. Pour Nom de l’étendue, entrez access_as_user.
   2. Pour Qui peut donner son consentement, vérifiez que l’option Administrateurs et utilisateurs est sélectionnée.
   3. Dans la zone Nom d’affichage du consentement administrateur, entrez Access TodoListService as a user.
   4. Dans Description du consentement de l’administrateur, entrez Accesses the TodoListService web API as a user.
   5. Dans la zone Nom d’affichage du consentement utilisateur, entrez Access TodoListService as a user.
   6. Dans la zone Description du consentement de l’utilisateur, entrez Accesses the TodoListService web API as a user.
   7. Pour État, conservez Activé.

9. Sélectionnez Ajouter une étendue.

Configurer le projet de service

Configurez le projet de service en fonction de l’API web inscrite.

1. Ouvrez la solution dans Visual Studio, puis ouvrez le fichier appsettings.json sous la racine du projet TodoListService.

2. Remplacez la valeur du paramètre Enter_the_Application_Id_here par la valeur ID client (ID d’application) de l’application que vous avez inscrite dans le portail Inscriptions d’applications dans les propriétés ClientID et Audience.

Ajouter la nouvelle étendue au fichier app.config

Pour ajouter la nouvelle étendue au fichier app.config de TodoListClient, effectuez les étapes suivantes :

1. Dans le dossier racine du projet TodoListClient, ouvrez le fichier app.config.

2. Collez l’ID d’application à partir de l’application que vous avez inscrite pour votre projet TodoListService dans le paramètre TodoListServiceScope, en remplaçant la chaîne {Enter the Application ID of your TodoListService from the app registration portal}.

Notes

Vérifiez que l’ID d’application utilise le format suivant : api://{TodoListService-Application-ID}/access_as_user (où {TodoListService-Application-ID} est le GUID représentant l’ID d’application de votre application TodoListService).

Inscrire l’application web (TodoListClient)

Inscrivez votre application TodoListClient dans Inscriptions d’applications au sein du portail Azure, puis configurez le code dans le projet TodoListClient. Si le client et le serveur sont considérés comme étant la même application, vous pouvez réutiliser l’application inscrite à l’étape 2. Utilisez la même application si vous voulez que les utilisateurs se connectent avec un compte Microsoft personnel.

Enregistrer l'application

Pour inscrire l’application TodoListClient, effectuez les étapes suivantes :

1. Connectez-vous au Centre d’administration de Microsoft Entra au minimum en tant qu’Administrateur d’application cloud.

2. Accédez à Identité>Applications>Inscriptions d’applications, puis sélectionnez Nouvelle inscription.

3. Sélectionnez Nouvelle inscription.

4. Quand la page Inscrire une application s’ouvre, entrez les informations d’inscription de votre application :

   1. Dans la section Nom, entez un nom d’application explicite qui s’affichera pour les utilisateurs de l’application (par exemple, NativeClient-DotNet-TodoListClient).
   2. Pour Types de comptes pris en charge, sélectionnez Comptes dans un annuaire organisationnel.
   3. Sélectionnez Inscrire pour créer l’application.

   Notes

   Dans le fichier app.config du projet TodoListClient, la valeur par défaut de ida:Tenant est définie sur common. Les valeurs possibles sont les suivantes :

   • common : Vous pouvez vous connecter à l’aide d’un compte professionnel ou scolaire ou d’un compte Microsoft personnel (car vous avez sélectionné Comptes dans un annuaire organisationnel lors d’une étape précédente).
   • organizations : Vous pouvez vous connecter à l’aide d’un compte professionnel ou scolaire.
   • consumers : Vous pouvez vous connecter à l’aide d’un compte Microsoft personnel uniquement.

5. Dans la page Vue d’ensemble de l’application, sélectionnez Authentification, puis effectuez les étapes suivantes pour ajouter une plateforme :

   1. Sous Configurations de plateformes, sélectionnez le bouton Ajouter une plateforme.
   2. Pour l’option Applications de bureau et mobiles, sélectionnez Application de bureau et mobiles.
   3. Pour les URI de redirection, activez la case à cocher https://login.microsoftonline.com/common/oauth2/nativeclient .
   4. Sélectionnez Configurer.

6. Sélectionnez API autorisées, puis effectuez les étapes suivantes pour ajouter des autorisations :

   1. Cliquez sur le bouton Ajouter une autorisation.
   2. Sélectionnez l’onglet Mes API.
   3. Dans la liste des API, sélectionnez API AppModelv2-NativeClient-DotNet-TodoListService ou le nom que vous avez entré pour l’API web.
   4. Si ce n’est pas déjà fait, cochez la case de l’autorisation access_as_user. Utilisez la zone de recherche, si nécessaire.
   5. Sélectionnez le bouton Ajouter des autorisations.

Configurer votre projet

Configurez votre projet TodoListClient en ajoutant l’ID d’application au fichier app.config.

1. Dans le portail Inscriptions d’applications, dans la page Vue d’ensemble, copiez la valeur de l’ID d’application (client) .

2. Dans le dossier racine du projet TodoListClient, ouvrez le fichier app.config, puis collez la valeur ID de l’application dans le paramètre ida:ClientId.

Exécuter vos projets

Démarrez les deux projets. Pour les utilisateurs de Visual Studio ;

1. Cliquez avec le bouton droit sur la solution Visual Studio, puis sélectionnez Propriétés

2. Dans Propriétés communes, sélectionnez Projet de démarrage, puis Plusieurs projets de démarrage.

3. Pour les deux projets, choisissez Démarrer en tant qu’action

4. Assurez-vous que le service TodoListService démarre en premier en le plaçant à la première position dans la liste à l’aide de la touche flèche haut.

Connectez-vous pour exécuter votre projet TodoListClient.

1. Appuyez sur F5 pour démarrer les projets. La page du service s’ouvre, ainsi que l’application de bureau.

2. Dans le projet TodoListClient, en haut à droite, sélectionnez Se connecter, puis connectez-vous avec les informations d’identification que vous avez utilisées pour inscrire votre application ou connectez-vous en tant qu’utilisateur dans le même annuaire.

   Si vous vous connectez pour la première fois, vous pouvez être invité à donner votre consentement à l’API web TodoListService.

   Pour vous permettre d’accéder à l’API web TodoListService et d’arranger la liste À faire, la connexion demande également le jeton d’accès à l’étendue access_as_user.

Pré-autoriser votre application cliente

Vous pouvez permettre aux utilisateurs d’autres annuaires d’accéder à votre API web en autorisant préalablement l’application cliente à accéder à votre API web. Pour ce faire, ajoutez l’ID d’application de l’application cliente à la liste des applications pré-autorisées pour votre API web. En ajoutant un client pré-autorisé, vous autorisez les utilisateurs à accéder à votre API web sans avoir à fournir de consentement.

1. Dans le portail Inscriptions d’applications, ouvrez les propriétés de votre application TodoListService.
2. Dans la section Exposer une API, sous Applications clientes autorisées, sélectionnez Ajouter une application cliente.
3. Dans la zone ID client, collez l’ID de l’application TodoListClient.
4. Dans la section Étendues autorisées, sélectionnez l’étendue de l’API web api://<Application ID>/access_as_user.
5. Sélectionnez Ajouter une application.

Exécuter votre projet

1. Appuyez sur F5 pour exécuter votre projet. Votre application TodoListClient s’ouvre.
2. En haut à droite, sélectionnez Se connecter, puis connectez-vous en utilisant un compte Microsoft personnel, comme un compte live.com ou hotmail.com, ou encore un compte professionnel ou scolaire.

Facultatif : Limiter l’accès de connexion à certains utilisateurs

Par défaut, tous les comptes personnels, tels que les comptes outlook.com ou live.com, ou les comptes professionnels ou scolaires d'organisations intégrées à Microsoft Entra ID, peuvent demander des jetons et accéder à votre API Web.

Pour spécifier quel utilisateur peut se connecter à votre application, modifiez la propriété TenantId dans le fichier appsettings.json.

Aide et support

Si vous avez besoin d’aide, si vous souhaitez signaler un problème ou si vous voulez en savoir plus sur vos options de support, consultez Aide et support pour les développeurs.

Étapes suivantes

Découvrez plus d’informations en créant une API web ASP.NET Core protégée dans cette série de didacticiels :

Didacticiel sur l’API web protégée