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

Bienvenue ! Ce n’est probablement pas la page que vous attendiez. Pendant que nous travaillons sur un correctif, ce lien devrait vous permettre d’accéder au bon article :

Démarrage rapide : appeler une API web ASP.NET protégée

Nous vous prions de nous excuser pour le désagrément et nous vous remercions de votre patience.

Dans ce guide de démarrage rapide, vous téléchargez et exécutez un exemple de code qui montre comment protéger une API web ASP.NET en limitant l’accès à ses ressources aux comptes autorisés uniquement. 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 vous pouvez demander un jeton d’accès afin d’accéder à une API web.

Prérequis

Cloner ou télécharger l’exemple

Vous pouvez obtenir l’exemple de deux manières :

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)

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

  1. Connectez-vous au centre d’administration Microsoft Entra en tant qu’administrateur d’applications au moins.

  2. Accédez à Identité>Applications>Inscriptions d’applications.

  3. 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 aurez besoin pour configurer le fichier de configuration Visual Studio pour ce projet (autrement dit, ClientId dans le fichier TodoListService\Web.config).

  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 Web.config sous la racine du projet TodoListService.

  2. Remplacez la valeur du paramètre ida:ClientId par la valeur ID client (ID d’application) de l’application que vous avez inscrite dans le portail Inscriptions d’applications.

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. Accédez au portail Inscriptions d’applications de la plateforme d’identités Microsoft pour les développeurs.

  2. Sélectionnez Nouvelle inscription.

  3. 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.
  4. 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.
  5. 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. Si vous utilisez 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 qui peut se connecter à votre application, utilisez l’une des options suivantes :

Option 1 : Limiter l’accès à une seule organisation (monolocataire)

Vous pouvez limiter l'accès de connexion à votre application aux comptes d'utilisateurs qui se trouvent dans un seul locataire Microsoft Entra, y compris les comptes invités de ce locataire. Ce scénario est courant pour les applications métier.

  1. Ouvrez le fichier App_Start\Startup.Auth, puis remplacez la valeur du point de terminaison de métadonnées qui est passée dans OpenIdConnectSecurityTokenProvider par https://login.microsoftonline.com/{Tenant ID}/v2.0/.well-known/openid-configuration. Vous pouvez également utiliser le nom du locataire, par exemple contoso.onmicrosoft.com.
  2. Dans le même fichier, affectez à la propriété ValidIssuer définie sur TokenValidationParameters la valeur https://sts.windows.net/{Tenant ID}/, et définissez l’argument ValidateIssuer sur true.

Option n°2 : Utiliser une méthode personnalisée pour valider les émetteurs

Vous pouvez implémenter une méthode personnalisée pour valider les émetteurs à l’aide du paramètre IssuerValidator. Pour plus d’informations sur ce paramètre, consultez la rubrique relative à la classe TokenValidationParameters.

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 dans la série de tutoriels suivante :