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

S’applique à : Les locataires de main-d’œuvre Locataires externes (en savoir plus)

Dans ce guide de démarrage rapide, vous utilisez un exemple d’application web pour vous montrer comment protéger une API web ASP.NET à l’aide de la plateforme d’identités Microsoft. L’exemple utilise la bibliothèque d’authentification Microsoft (MSAL) pour gérer l’authentification et l’autorisation.

Conditions préalables

• Un compte Azure avec un abonnement actif. Créez gratuitement un compte.
• Inscrivez une nouvelle application dans le Centre d’administration Microsoft Entra et enregistrez ses identificateurs à partir de la page Vue d’ensemble de l’application. Pour plus d’informations, consultez Inscrire une application.
  • Nom : NewWebAPI1
  • Types de comptes pris en charge : comptes dans cet annuaire organisationnel uniquement (locataire unique)

ASP.NET

• Visual Studio 2022. Téléchargez Visual Studio gratuitement.

ASP.NET Core

• Visual Studio Code

Exposer l’API

Une fois l’API inscrite, vous pouvez configurer son autorisation en définissant les étendues qu’elle expose aux applications clientes. Les applications clientes demandent l’autorisation d’effectuer des opérations en passant un jeton d’accès et les requêtes associées à l’API web protégée. L'API web effectue ensuite l’opération demandée uniquement si le jeton d’accès qu’elle reçoit contient les étendues nécessaires.

ASP.NET

1. 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 portée, 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 la zone de description du consentement administrateur , entrez Accesses the TodoListService web API as a user.
   5. Dans la zone nom d’affichage de consentement utilisateur, entrez Access TodoListService as a user.
   6. Dans la zone de description du consentement de l’utilisateur , entrez Accesses the TodoListService web API as a user.
   7. Pour l’état, conservez activé.

2. Sélectionnez Ajouter une étendue.

ASP.NET Core

Ajouter des autorisations déléguées (étendues)

Une API doit publier au moins une étendue, également appelée Autorisation déléguée, pour que les applications clientes obtiennent un jeton d’accès pour un utilisateur. Pour publier une étendue, effectuez les étapes suivantes :

1. Dans la page Inscriptions d’applications , sélectionnez l’application API que vous avez créée (ciam-ToDoList-api) pour ouvrir sa page Vue d’ensemble .

2. Sous Gérer, sélectionnez Exposer une API.

3. En haut de la page, en regard de l’URI d’ID d’application, sélectionnez le lien Ajouter pour générer un URI unique pour cette application.

4. Acceptez l’URI d’ID d’application proposé, par api://{clientId}exemple, puis sélectionnez Enregistrer. Lorsque votre application web demande un jeton d’accès pour l’API web, elle ajoute l’URI comme préfixe pour chaque étendue que vous définissez pour l’API.

5. Sous Étendues définies par cette API, sélectionnez Ajouter une étendue.

6. Entrez les valeurs suivantes qui définissent un accès en lecture à l’API, puis sélectionnez Ajouter une étendue pour enregistrer vos modifications :

   Propriété	Valeur
   Nom de l’étendue	ToDoList.Read
   Qui peut donner son consentement	Administrateurs uniquement
   Nom d’affichage du consentement administrateur	Lire la liste ToDo des utilisateurs à l’aide de « TodoListApi »
   Description du consentement de l'administrateur	Autorisez l’application à lire la liste ToDo de l’utilisateur à l’aide de « TodoListApi ».
   État	Activé

7. Sélectionnez à nouveau Ajouter une étendue , puis entrez les valeurs suivantes qui définissent une étendue d’accès en lecture et en écriture à l’API. Sélectionnez Ajouter une étendue pour enregistrer vos modifications :

   Propriété	Valeur
   Nom de l’étendue	ToDoList.ReadWrite
   Qui peut donner son consentement	Administrateurs uniquement
   Nom d’affichage du consentement administrateur	Les utilisateurs lisent et écrivent dans la liste de tâches à l’aide de l'API « ToDoListApi »
   Description du consentement de l'administrateur	Autoriser l’application à lire et écrire la liste ToDo de l’utilisateur à l’aide de « ToDoListApi »
   État	Activé

En savoir plus sur le principe du privilège minimum lors de la publication d’autorisations pour une API web.

Ajouter des autorisations d’application (rôles d’application)

Une API doit publier au moins un rôle d’application pour les applications, également appelée autorisation d’application, pour que les applications clientes obtiennent un jeton d’accès en tant que telles. Les autorisations d’application sont le type d’autorisations que les API doivent publier lorsqu’elles souhaitent permettre aux applications clientes de s’authentifier correctement en tant qu’elles-mêmes et qu’elles n’ont pas besoin de connecter des utilisateurs. Pour publier une autorisation d'application, procédez comme suit :

1. Dans la page Inscriptions d’applications , sélectionnez l’application que vous avez créée (par exemple , ciam-ToDoList-api) pour ouvrir sa page Vue d’ensemble .

2. Sous Gérer, sélectionnez Rôles d’application.

3. Sélectionnez Créer un rôle d’application, entrez les valeurs suivantes, puis sélectionnez Appliquer pour enregistrer vos modifications :

   Propriété	Valeur
   Nom d’affichage	ToDoList.Read.All
   Types de membres autorisés	Applications
   Valeur	ToDoList.Read.All
   Descriptif	Autoriser l’application à lire la liste ToDo de chaque utilisateur à l’aide de « TodoListApi »
   Voulez-vous activer le rôle de cette application ?	Maintenez cette option cochée

4. Sélectionnez à nouveau Créer un rôle d’application , puis entrez les valeurs suivantes pour le deuxième rôle d’application, puis sélectionnez Appliquer pour enregistrer vos modifications :

   Propriété	Valeur
   Nom d’affichage	ToDoList.ReadWrite.All
   Types de membres autorisés	Applications
   Valeur	ToDoList.ReadWrite.All
   Descriptif	Autoriser l’application à lire et écrire la liste ToDo de chaque utilisateur à l’aide de « ToDoListApi »
   Voulez-vous activer le rôle de cette application ?	Maintenez cette option cochée

Cloner ou télécharger l’exemple d’application

Pour obtenir l’exemple d’application, vous pouvez le cloner à partir de GitHub ou le télécharger en tant que fichier .zip .

ASP.NET

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

• Téléchargez-le en tant que fichier ZIP.

Conseil / Astuce

Pour éviter les erreurs provoquées par des limitations de longueur de chemin d’accès 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.

ASP.NET Core

git clone https://github.com/Azure-Samples/ms-identity-ciam-dotnet-tutorial.git

• Téléchargez le fichier .zip. Extrayez-le dans un chemin de fichier où la longueur du nom est inférieure à 260 caractères.

Configurer l’exemple d’application

Configurez l’exemple de code pour qu’il corresponde à l’API web inscrite.

ASP.NET

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

2. Remplacez la valeur de Enter_the_Application_Id_here par la valeur ID client (ID d'application) de l'application que vous avez enregistrée dans le portail des inscriptions d'applications, à la fois dans les propriétés ClientID et Audience.

Ajouter la nouvelle étendue au fichier app.config

Pour ajouter la nouvelle étendue au fichier todoListClient app.config , procédez comme suit :

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}.

Remarque

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 les inscriptions d’applications dans le Centre d’administration Microsoft Entra, puis configurez le code dans le projet TodoListClient. Si le client et le serveur sont considérés comme 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 Microsoft Entra en tant qu’administrateur d’application cloud au moins.

2. Accédez à Entra ID>inscriptions d’application et sélectionnez Nouvelle inscription.

3. Sélectionnez Nouvelle inscription.

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

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

   Remarque

   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 n’importe quel annuaire organisationnel à l’é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 procédez comme suit pour ajouter une plateforme :

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

6. Sélectionnez les autorisations d’API, puis procédez comme suit pour ajouter des autorisations :

   1. Sélectionnez le bouton Ajouter une autorisation .
   2. Sélectionnez l’onglet Mes API .
   3. Dans la liste des API, sélectionnez AppModelv2-NativeClient-DotNet-TodoListService API ou le nom que vous avez entré pour l’API web.
   4. Cochez la case access_as_user autorisation si elle n’est pas déjà sélectionnée. 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 des inscriptions d’applications, dans la page Vue d’ensemble , copiez la valeur de l’ID d’application (client).

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

ASP.NET Core

1. Dans votre IDE, ouvrez le dossier du projet, ms-identity-ciam-dotnet-tutorial/2-Authorization/3-call-own-api-dotnet-core-daemon/ToDoListAPI, contenant l’exemple.

2. Ouvrez le fichier appsettings.json, qui contient l’extrait de code suivant :

   {
     "AzureAd": {
       "Instance": "Enter_the_Authority_URL_Here", //For external tenants, use instance in the form of "https://Enter_the_Tenant_Subdomain_Here.ciamlogin.com/"
       "TenantId": "Enter_the_Tenant_Id_Here",
       "ClientId": "Enter_the_Application_Id_Here",
       "Scopes": {
         "Read": ["ToDoList.Read", "ToDoList.ReadWrite"],
         "Write": ["ToDoList.ReadWrite"]
       },
       "AppPermissions": {
         "Read": ["ToDoList.Read.All", "ToDoList.ReadWrite.All"],
         "Write": ["ToDoList.ReadWrite.All"]
       }
     },
     "Logging": {...},
     "AllowedHosts": "*"
   }
   

   Recherchez les valeurs suivantes :

   • ClientId : identificateur de l’application, également appelé client. Remplacez le value texte entre guillemets par l’ID d’application (client) enregistré précédemment à partir de la page Vue d’ensemble de l’application inscrite.
   • TenantId : identificateur du locataire où l’application est inscrite. Remplacez le texte value entre guillemets par la valeur ID d'annuaire (locataire) qui a été enregistrée précédemment à partir de la page Vue d'ensemble de l'application enregistrée.
   • Instance - Il spécifie le répertoire à partir duquel la bibliothèque d’authentification Microsoft (MSAL) peut demander des jetons. Remplacez Enter_the_Authority_URL_Here par l’une des valeurs suivantes en fonction de votre scénario :
     • Pour les locataires de main-d’œuvre, utilisez https://login.microsoftonline.com/ l’instance.
     • Pour les locataires externes, ajoutez une URL d’autorité sous la forme de https://<Enter_the_Tenant_Subdomain_Here>.ciamlogin.com/

Exécuter l’exemple d’application

ASP.NET

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

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

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

3. Pour les deux projets, choisissez Démarrer comme 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 todoListClient, en haut à droite, sélectionnez Se connecter, puis connectez-vous avec les mêmes informations d’identification que celles que vous avez utilisées pour inscrire votre application ou connectez-vous en tant qu’utilisateur dans le même répertoire.

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

   Pour vous aider à accéder à l’API web TodoListService et à manipuler la liste de tâches, la connexion demande également un 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 le consentement.

1. Dans le portail des 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 d’application de l’application TodoListClient.
4. Dans la section Étendues autorisées , sélectionnez l’étendue de l’API api://<Application ID>/access_as_user web.
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 à l’aide d’un compte Microsoft personnel, tel qu’un live.com ou un compte hotmail.com , ou un compte professionnel ou scolaire.

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

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

Pour spécifier qui peut se connecter à votre application, en modifiant la TenantId propriété dans le fichier appsettings.json .

ASP.NET Core

1. Exécutez la commande suivante à partir de la racine de votre répertoire de projet d’API web pour démarrer l’application :

   dotnet run
   

2. Si tout a fonctionné correctement, votre terminal affiche une sortie similaire à ce qui suit :

    Building...
        info: Microsoft.Hosting.Lifetime[14]
              Now listening on: https://localhost:{port}
        info: Microsoft.Hosting.Lifetime[0]
              Application started. Press Ctrl+C to shut down.
        info: Microsoft.Hosting.Lifetime[0]
              Hosting environment: Development
   ...
   

   Enregistrez le numéro de port dans l’URL https://localhost:{port}.

3. Pour vérifier que le point de terminaison est protégé, mettez à jour l’URL de base dans la commande cURL suivante pour qu’elle corresponde à celle que vous avez reçue à l’étape précédente, puis exécutez la commande :

   curl -k -X GET https://localhost:<your-api-port>/api/todolist -w "%{http_code}\n"
   

   La réponse attendue est 401 Non autorisée.

Étapes suivantes

Découvrez comment protéger une API web ASP.NET Core avec la plateforme d’identités Microsoft.

Tutoriel : Créer et sécuriser une API web ASP.NET Core avec la plateforme d’identités Microsoft