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 :
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
- Compte Azure avec un abonnement actif. Créez un compte gratuitement.
- Visual Studio 2017 ou 2019. Téléchargez Visual Studio gratuitement.
Cloner ou télécharger l’exemple
Vous pouvez obtenir l’exemple 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
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.
Connectez-vous au centre d’administration Microsoft Entra en tant qu’administrateur d’applications au moins.
Accédez à Identité>Applications>Inscriptions d’applications.
Sélectionnez Nouvelle inscription.
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.Pour Types de comptes pris en charge, sélectionnez Comptes dans un annuaire organisationnel.
Sélectionnez Inscrire pour créer l’application.
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).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 :- Pour Nom de l’étendue, entrez
access_as_user
. - Pour Qui peut donner son consentement, vérifiez que l’option Administrateurs et utilisateurs est sélectionnée.
- Dans la zone Nom d’affichage du consentement administrateur, entrez
Access TodoListService as a user
. - Dans Description du consentement de l’administrateur, entrez
Accesses the TodoListService web API as a user
. - Dans la zone Nom d’affichage du consentement utilisateur, entrez
Access TodoListService as a user
. - Dans la zone Description du consentement de l’utilisateur, entrez
Accesses the TodoListService web API as a user
. - Pour État, conservez Activé.
- Pour Nom de l’étendue, entrez
Sélectionnez Ajouter une étendue.
Configurer le projet de service
Configurez le projet de service en fonction de l’API web inscrite.
Ouvrez la solution dans Visual Studio, puis ouvrez le fichier Web.config sous la racine du projet TodoListService.
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 :
Dans le dossier racine du projet TodoListClient, ouvrez le fichier app.config.
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 :
Accédez au portail Inscriptions d’applications de la plateforme d’identités Microsoft pour les développeurs.
Sélectionnez Nouvelle inscription.
Quand la page Inscrire une application s’ouvre, entrez les informations d’inscription de votre application :
- Dans la section Nom, entez un nom d’application explicite qui s’affichera pour les utilisateurs de l’application (par exemple, NativeClient-DotNet-TodoListClient).
- Pour Types de comptes pris en charge, sélectionnez Comptes dans un annuaire organisationnel.
- 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 surcommon
. 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.
Dans la page Vue d’ensemble de l’application, sélectionnez Authentification, puis effectuez les étapes suivantes pour ajouter une plateforme :
- Sous Configurations de plateformes, sélectionnez le bouton Ajouter une plateforme.
- Pour l’option Applications de bureau et mobiles, sélectionnez Application de bureau et mobiles.
- Pour les URI de redirection, activez la case à cocher
https://login.microsoftonline.com/common/oauth2/nativeclient
. - Sélectionnez Configurer.
Sélectionnez API autorisées, puis effectuez les étapes suivantes pour ajouter des autorisations :
- Cliquez sur le bouton Ajouter une autorisation.
- Sélectionnez l’onglet Mes API.
- Dans la liste des API, sélectionnez API AppModelv2-NativeClient-DotNet-TodoListService ou le nom que vous avez entré pour l’API web.
- 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.
- Sélectionnez le bouton Ajouter des autorisations.
Configurer votre projet
Configurez votre projet TodoListClient en ajoutant l’ID d’application au fichier app.config.
Dans le portail Inscriptions d’applications, dans la page Vue d’ensemble, copiez la valeur de l’ID d’application (client) .
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 :
Cliquez avec le bouton droit sur la solution Visual Studio, puis sélectionnez Propriétés
Dans Propriétés communes, sélectionnez Projet de démarrage, puis Plusieurs projets de démarrage.
Pour les deux projets, choisissez Démarrer en tant qu’action
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.
Appuyez sur F5 pour démarrer les projets. La page du service s’ouvre, ainsi que l’application de bureau.
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.
- Dans le portail Inscriptions d’applications, ouvrez les propriétés de votre application TodoListService.
- Dans la section Exposer une API, sous Applications clientes autorisées, sélectionnez Ajouter une application cliente.
- Dans la zone ID client, collez l’ID de l’application TodoListClient.
- Dans la section Étendues autorisées, sélectionnez l’étendue de l’API web
api://<Application ID>/access_as_user
. - Sélectionnez Ajouter une application.
Exécuter votre projet
- Appuyez sur F5 pour exécuter votre projet. Votre application TodoListClient s’ouvre.
- 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.
- 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
parhttps://login.microsoftonline.com/{Tenant ID}/v2.0/.well-known/openid-configuration
. Vous pouvez également utiliser le nom du locataire, par exemplecontoso.onmicrosoft.com
. - Dans le même fichier, affectez à la propriété
ValidIssuer
définie surTokenValidationParameters
la valeurhttps://sts.windows.net/{Tenant ID}/
, et définissez l’argumentValidateIssuer
surtrue
.
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 :