Appeler une API web ASP.NET Core avec insomnie

Article
05/24/2024

Cet article vous montre comment appeler une API web ASP.NET Core protégée à l’aide de insomnie. L’insomnie est une application qui vous permet d’envoyer des requêtes HTTP à une API web pour tester ses stratégies d’autorisation et de contrôle d’accès (authentification). Dans cet article, vous inscrivez une application web et une API web dans un locataire. L’application web sert à obtenir un jeton d’accès généré par le plateforme d'identités Microsoft. Ensuite, vous utilisez le jeton pour effectuer un appel autorisé à l’API web à l’aide d’Insomnie.

Cet article vous montre comment appeler une API web ASP.NET Core protégée à l’aide de insomnie. L’insomnie est une application qui vous permet d’envoyer des requêtes HTTP à une API web pour tester ses stratégies d’autorisation et de contrôle d’accès (authentification). À la suite du Tutoriel Implémenter un point de terminaison protégé pour votre API, où vous avez créé une API protégée, vous devez inscrire une application web auprès de la plateforme d’identités Microsoft pour générer un jeton d’accès. Ensuite, vous utilisez le jeton pour effectuer un appel autorisé à l’API à l’aide d’Insomnie.

Prérequis

Compte Azure avec un abonnement actif. Créez un compte gratuitement.
Ce compte Azure doit disposer des autorisations nécessaires pour gérer des applications. Les rôles Microsoft Entra suivants incluent les autorisations requises :
- Administrateur d’application
- Développeur d’applications
- Administrateur d’application cloud
Téléchargez et installez Insomnie. Vous utilisez Insomnie pour obtenir un jeton d’accès pour vos demandes d’API.
Exigence minimale de SDK .NET 8.0.

Compte Azure avec un abonnement actif. Créez un compte gratuitement.
Ce compte Azure doit disposer des autorisations nécessaires pour gérer des applications. Les rôles Microsoft Entra suivants incluent les autorisations requises :
- Administrateur d’application
- Développeur d’applications
- Administrateur d'applications cloud
Réalisation de la série de tutoriels :
Téléchargez et installez Insomnie.

Inscrire une application

Avec la plateforme d’identités Microsoft, votre application doit d’abord être inscrite avant de pouvoir fournir des services de gestion des identités et des accès. Au moment d’inscrire l’application, vous pouvez spécifier le nom et le type de l’application ainsi que l’audience de connexion. L’audience de connexion spécifie les types de comptes d’utilisateur autorisés à se connecter à une application donnée.

Inscrire l’API web

Conseil

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

Suivez ces étapes pour créer l’inscription de l’API web :

Connectez-vous au centre d’administration de Microsoft Entra au minimum en tant que Développeur d’application.
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.
Accédez à Identité>Applications>Inscriptions d’applications.
Sélectionnez Nouvelle inscription.
Attribuez un Nom à l’application, par exemple NewWebAPI1.
Pour les Types de comptes pris en charge, sélectionnez Comptes dans cet annuaire organisationnel. Pour plus d’informations sur les différents types de comptes, sélectionnez l’option M’aider à choisir.
Sélectionnez Inscription.
Vous pouvez voir le volet Vue d’ensemble de l’application une fois l’inscription terminée. Enregistrez l’ID de l’annuaire (locataire) et l’ID d’application (client) à utiliser dans les étapes suivantes.

Notes

Il est possible de modifier les Types de comptes pris en charge. Pour cela, reportez-vous à Modifier les comptes pris en charge par une application.

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 demandes associées à l’API web protégée. L’API web n’effectue ensuite l’opération demandée que si le jeton d’accès qu’elle reçoit est valide.

Sous Gérer, sélectionnez Exposer une API > Ajouter une étendue. Acceptez l’URI d’ID d’application (api://{clientId})proposée en sélectionnant Enregistrer et continuer. {clientId} est la valeur enregistrée depuis la page Vue d’ensemble. Entrez ensuite les informations suivantes :
1. Pour Nom de l’étendue, entrez Forecast.Read.
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 Read forecast data.
4. Dans Description du consentement de l’administrateur, entrez Allows the application to read weather forecast data.
5. Dans la zone Nom d’affichage du consentement utilisateur, entrez Read forecast data.
6. Dans la zone Description du consentement de l’utilisateur, entrez Allows the application to read weather forecast data.
7. Vérifiez que l’État défini est Activé.
Sélectionnez Ajouter une étendue. Si l’étendue a été correctement entrée, elle apparaît dans le volet Exposer une API volet.

Inscrire l’application web

Il n’est pas suffisant d’avoir une API web, vous avez également besoin d’une application web pour obtenir un jeton d’accès pour accéder à l’API web.

Effectuez les étapes suivantes pour créer l’inscription d’application web :

Sélectionnez Accueil pour revenir à la page d’accueil. Accédez à Identité>Applications>Inscriptions d’applications.
Sélectionnez Nouvelle inscription.
Entrez un nom pour l'application, tel que web-app-calls-web-api.
Pour les Types de comptes pris en charge, sélectionnez Comptes dans cet annuaire organisationnel. Pour plus d’informations sur les différents types de comptes, sélectionnez l’option M’aider à choisir.
Sous URI de redirection (facultatif), sélectionnez Web, puis entrez http://localhost dans la zone de texte de l’URL.
Sélectionnez Inscrire.

Connectez-vous au centre d’administration de Microsoft Entra au minimum en tant que Développeur d’application.
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.
Accédez à Identité>Applications>Inscriptions d’applications.
Sélectionnez Nouvelle inscription.
Entrez un nom pour l'application, tel que web-app-calls-web-api.
Pour les Types de comptes pris en charge, sélectionnez Comptes dans cet annuaire organisationnel. Pour plus d’informations sur les différents types de comptes, sélectionnez l’option M’aider à choisir.
Sous URI de redirection (facultatif), sélectionnez Web, puis entrez http://localhost dans la zone de texte de l’URL.
Sélectionnez Inscrire.

Vous pouvez voir le volet Vue d’ensemble de l’application une fois l’inscription terminée. Enregistrez l’ID de l’annuaire (locataire) et l’ID d’application (client) à utiliser dans les étapes suivantes.

Ajouter un secret client

Une clé secrète client est une valeur de chaîne dont se sert votre application pour s’identifier elle-même, qui est parfois appelée mot de passe d’application. L’application web se sert de la clé secrète client pour prouver son identité au moment de demander des jetons.

Suivez ces étapes pour configurer une clé secrète client :

Dans le volet Vue d’ensemble, sous Gérer, sélectionnez Certificats et secrets>Secrets client>Nouveau secret client.
Ajoutez une description pour votre clé secrète client, par exemple Ma clé secrète client.
Sélectionnez un délai d’expiration pour le secret ou spécifiez une durée de vie personnalisée.
- La durée de vie d’une clé secrète client est limitée à deux ans (24 mois) voire moins. Vous ne pouvez pas spécifier une durée de vie personnalisée supérieure à 24 mois.
- Microsoft vous recommande de définir une valeur d’expiration inférieure à 12 mois.
Sélectionnez Ajouter.
Veillez à enregistrer la Valeur de la clé secrète client. Cette valeur secrète ne sera plus jamais affichée lorsque vous aurez quitté cette page.

Pour plus d’informations sur la façon de stocker en toute sécurité votre clé secrète client, consultez Meilleures pratiques pour la gestion des secrets dans Key Vault.

Ajouter des autorisations pour accéder à votre API web

En spécifiant les étendues d’une API web, l’application web peut obtenir un jeton d’accès contenant les étendues fournies par la plateforme d’identités Microsoft. À l’intérieur du code, l’API web peut ensuite fournir un accès basé sur les autorisations à ses ressources en fonction des étendues se trouvant dans le jeton d’accès.

Effectuez les étapes ci-dessous pour configurer les autorisations du client pour l’API web :

Dans le volet Présentation de votre application, sous Gérer, sélectionnez Autorisations API>Ajouter une autorisation>API utilisées par mon organisation.
Sélectionnez NewWebAPI1 ou l’API à laquelle vous souhaitez ajouter les autorisations.
Sous Sélectionner des autorisations, cochez la case en regard de Forecast.Read. Vous devrez peut-être développer la liste Autorisation. Les autorisations dont doit disposer l’application cliente pour le compte de l’utilisateur connecté sont alors sélectionnées.
Sélectionnez Ajouter des autorisations pour terminer le processus.

Une fois ces autorisations ajoutées à votre API, les autorisations sélectionnées doivent figurer dans Autorisations configurées.

Il se peut que vous remarquiez aussi la présence de l’autorisation User.Read pour l’API Microsoft Graph. Cette autorisation est automatiquement ajoutée lorsque vous inscrivez une application.

Tester l’API web

Pour vous assurer que votre API est opérationnelle et prête à gérer les requêtes, procédez comme suit :

Clonez le référentiel ms-identity-docs-code-dotnet.

git clone https://github.com/Azure-Samples/ms-identity-docs-code-dotnet.git

Accédez à ms-identity-docs-code-dotnet/web-api et ouvrez appsettings.json, remplacez le {APPLICATION_CLIENT_ID} et {DIRECTORY_TENANT_ID} par les valeurs suivantes :
- {APPLICATION_CLIENT_ID} correspond à l’ID d’application (client) de l’API web dans le volet Vue d’ensemble de l’application.
- {DIRECTORY_TENANT_ID} correspond à l’ID de répertoire (locataire) de l’API web dans le volet Vue d’ensemble de l’application.
Exécutez la commande suivante pour démarrer l’application :
```
dotnet run
```
Une sortie similaire à la suivante apparaît. Enregistrez le numéro de port dans l’URL https://localhost:{port}.
```
...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:{port}
...
```

Tester l’API web

Pour vous assurer que votre API est opérationnelle et prête à gérer les requêtes, procédez comme suit :

Accédez à l’API web qui a été créée dans Tutoriel : Créer un projet ASP.NET Core et configurer l’API, par exemple NewWebAPILocal, puis ouvrez le dossier.
Ouvrez une nouvelle fenêtre de terminal et accédez au dossier où se trouve le projet de l’API web.
- .NET 6.0
- .NET 7.0
1. Exécutez la commande suivante pour démarrer l’application :
```
dotnet run
```
1. Ouvrir une nouvelle fenêtre de terminal, puis exécutez la commande suivante pour démarrer l’application sur le profil https :
```
dotnet run -launch-profile https`
```
Une sortie similaire à la suivante apparaît. Enregistrez le numéro de port dans l’URL https://localhost:{port}.
```
...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:{port}
...
```

Configurer une demande autorisée sur l’API web en insomnie

Pour obtenir un jeton d’accès pour vos demandes d’API, procédez comme suit :

Lancez l’application Insomnie.
Sélectionnez nouvelle requête HTTP, ou vous pouvez utiliser Ctrl+ N pour créer une requête HTTP.
Dans le modal Nouvelle requête, sélectionnez une méthode GET dans la liste déroulante.
Pour l’URL de la demande, entrez l’URL du point de terminaison exposé par l’API web, https://localhost:{port}/weatherforecast.
Dans le menu déroulant Auth, sélectionnez OAuth 2.0. Cela affiche le formulaire OAuth 2.0.

Entrez les valeurs suivantes dans le formulaire OAuth 2.0 :

Paramètre	Valeur
TYPE DE SUBVENTION	Sélectionner Code d’autorisation
URL D'AUTORISATION	`https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize` Remplacer `{tenantId}` par l'ID d'annuaire (locataire)
URL DU JETON D'ACCÈS	`https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token` Remplacez `{tenantId}` par l’ID d’annuaire (locataire).
ID CLIENT	Valeur d’ID d’application (client) de l’inscription d’application web.
CLÉ SECRÈTE CLIENT	Valeur de clé secrète client de l’inscription d’application web.
URL DE REDIRECTION	Entrez `http://localhost`, qui définit l'URL de REDIRECT sur l'URI de redirection enregistré avec Microsoft Entra ID.
Options avancées>PORTÉ	`api://{application_client_id}/Forecast.Read` Accédez à l’inscription de votre application web, sous Gérer, sélectionnez Autorisations des API, puis Forecast.Read. Copiez la valeur dans la zone de texte, qui contient la valeur d’étendue.

Obtenir un jeton d’accès et envoyer une requête à l’API web

Une fois ces valeurs saisies, sélectionnez Récupérer les jetons à la fin du formulaire. Cela lance une fenêtre de navigateur Insomnia dans laquelle vous vous authentifiez avec vos informations d'identification utilisateur. Veillez à autoriser les fenêtres contextuelles à partir de l’application Insomnie dans le navigateur.
Après l’authentification, sélectionnez Envoyer pour envoyer la requête au point de terminaison de l’API web protégée.

Avec un jeton d’accès valide inclus dans la demande, la réponse attendue est 200 OK avec une sortie similaire à la sortie suivante :

[
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": -16,
    "summary": "Scorching",
    "temperatureF": 4
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 1,
    "summary": "Sweltering",
    "temperatureF": 33
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 26,
    "summary": "Freezing",
    "temperatureF": 78
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 54,
    "summary": "Mild",
    "temperatureF": 129
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 11,
    "summary": "Bracing",
    "temperatureF": 51
  }
]

Pour plus d’informations sur le flux de code d’autorisation OAuth 2.0 et les types d’applications, consultez :

Partage via

Appeler une API web ASP.NET Core avec insomnie

Prérequis