Appeler une API web ASP.NET Core avec cURL

Cet article vous montre comment appeler une API web ASP.NET Core protégée à l’aide de cURL (Client URL). cURL est un outil en ligne de commande dont se servent les développeurs pour transférer des données vers et depuis un serveur. 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 ce jeton pour effectuer un appel autorisé à l’API web à l’aide de cURL.

Cet article vous montre comment appeler une API web ASP.NET Core protégée à l’aide de cURL (Client URL). cURL est un outil en ligne de commande dont se servent les développeurs pour transférer des données vers et depuis un serveur. À 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 de cURL.

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'applications cloud
• Télécharger et installer cURL sur votre station de travail.
• Configuration minimale requise : SDK .NET 6.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 :
  • Tutoriel : Inscrire une API web auprès de la plateforme d’identités Microsoft.
  • Tutoriel : Créer et configurer un projet ASP.NET Core pour l’authentification.
  • Tutoriel : Implémenter un point de terminaison protégé pour votre API.
• Télécharger et installer cURL sur votre station de travail.

Inscrire une application avec la plateforme d’identités Microsoft

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 :

1. Connectez-vous au centre d’administration de Microsoft Entra au minimum en tant que Développeur d’application.

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.

4. Sélectionnez Nouvelle inscription.

5. Attribuez un Nom à l’application, par exemple NewWebAPI1.

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

7. Sélectionnez Inscription.

   

8. Le volet Vue d’ensemble de l’application s’affiche à la fin de l’inscription. Inscrivez l’ID de l’annuaire (locataire) et l’ID d’application (client) à utiliser dans le code source de votre application.

   

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.

1. Sous Gérer, sélectionnez Exposer une API > Ajouter une étendue. Acceptez l’URI d’ID d’application(api://{clientId}) proposé 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é.

2. Sélectionnez Ajouter une étendue. Si l’étendue a été entrée correctement, elle figure dans le volet Exposer une API.

   

Inscrire l’application web

Disposer d’une API web n’est cependant pas suffisant. En effet, vous avez également besoin d’une application web pour obtenir un jeton d’accès et ainsi accéder à l’API web.

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

1. Sélectionnez Accueil pour revenir à la page d’accueil. Accédez à Identité>Applications>Inscriptions d’applications.
2. Sélectionnez Nouvelle inscription.
3. Attribuez un Nom à l’application, par exemple web-app-calls-web-api.
4. 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.
5. Sous URI de redirection (facultatif), sélectionnez Web, puis entrez http://localhost dans la zone de texte de l’URL.
6. Sélectionnez Inscrire.

1. Connectez-vous au centre d’administration de Microsoft Entra au minimum en tant que Développeur d’application.
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.
4. Sélectionnez Nouvelle inscription.
5. Attribuez un nom à l’application, par exemple web-app-calls-web-api.
6. 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.
7. Sous URI de redirection (facultatif), sélectionnez Web, puis entrez http://localhost dans la zone de texte de l’URL.
8. Sélectionnez Inscrire.

Une fois l’inscription terminée, l’inscription de l’application s’affiche dans le volet Vue d’ensemble. 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 :

1. Dans le volet Vue d’ensemble, sous Gérer, sélectionnez Certificats et secrets>Secrets client>Nouveau secret client.

2. Ajoutez une description pour votre clé secrète client, par exemple Ma clé secrète client.

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

4. Sélectionnez Ajouter.

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

Ajouter des autorisations d’application pour autoriser l’accès à une API web

En spécifiant les étendues d’une API web dans l’inscription de l’application web, celle-ci 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 ces étapes pour configurer les autorisations de l’application web pour l’API web :

1. Dans le volet Vue d’ensemble de votre application web (web-app-that-calls-web-api), sous Gérer, sélectionnez Autorisations d’API>Ajouter une autorisation>Mes API.
2. Sélectionnez NewWebAPI1 ou l’API à laquelle vous souhaitez ajouter les autorisations.
3. 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.
4. 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

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

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

2. Accédez au dossier ms-identity-docs-code-dotnet/web-api, ouvrez le fichier ./appsettings.json, puis remplacez {APPLICATION_CLIENT_ID} et {DIRECTORY_TENANT_ID}, sachant que :

   • {APPLICATION_CLIENT_ID} correspond à l’ID d’application (client) de l’API web dans le volet Vue d’ensemble et la section Inscriptions d’applications de l’application.
   • {DIRECTORY_TENANT_ID} correspond à l’ID de répertoire (locataire) de l’API web dans le volet Vue d’ensemble et la section Inscriptions d’applications de l’application.

3. Exécutez la commande suivante pour démarrer l’application :

   .NET 6.0

   dotnet run
   

   .NET 7.0

   dotnet run --launch-profile https
   

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

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

2. Ouvrez une nouvelle fenêtre de terminal et accédez au dossier où se trouve le projet de l’API web.

.NET 6.0

1. Exécutez la commande suivante pour démarrer l’application :

   dotnet run
   

.NET 7.0

1. Exécutez la commande suivante pour démarrer l’application sur le profil https :

   dotnet run --launch-profile https
   

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

Demander un code d’autorisation

Le flux de code d'autorisation commence par le client dirigeant l'utilisateur vers le point de terminaison /authorize . Dans cette demande, le client demande l’autorisation Forecast.Read à l’utilisateur.

https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/authorize?client_id={web-app-calls-web-api_application_client_id}&response_type=code&redirect_uri=http://localhost&response_mode=query&scope=api://{web_API_application_client_id}/Forecast.Read

1. Copiez l’URL, remplacez les paramètres suivants, puis collez-la dans votre navigateur :

   • {tenant_id} est l’ID de l’annuaire (locataire) de l’application web.
   • {web-app-calls-web-api_application_client_id} est l’ID d’application (client) dans le volet Vue d’ensemble de l’application web (web-app-calls-web-api).
   • {web_API_application_client_id} est l’ID d’application (client) dans le volet Vue d’ensemble de l’API web (NewWebAPI1).

2. Connectez-vous en tant qu’utilisateur du locataire Microsoft Entra où les applications sont inscrites. Acceptez les demandes d’accès, si nécessaire.

3. Votre navigateur est alors redirigé vers http://localhost/. Dans la barre de navigation de votre navigateur, copiez le {authorization_code} pour l’utiliser dans les étapes suivantes. L’URL prend la forme de l’extrait de code suivant :

   http://localhost/?code={authorization_code}
   

Utiliser un code d’autorisation et cURL pour obtenir un jeton d’accès

Vous pouvez maintenant utiliser cURL pour demander un jeton d’accès à la plateforme d’identités Microsoft.

1. Copiez la commande cURL dans l’extrait de code suivant. Remplacez les valeurs entre parenthèses par les paramètres suivants dans votre terminal. Veillez à supprimer les parenthèses :

   curl -X POST https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token \
   -d 'client_id={web-app-calls-web-api_application_client_id}' \
   -d 'api://{web_API_application_client_id}/Forecast.Read' \
   -d 'code={authorization_code}&session_state={web-app-calls-web-api_application_client_id}' \
   -d 'redirect_uri=http://localhost' \
   -d 'grant_type=authorization_code' \
   -d 'client_secret={client_secret}'
   

   • {tenant_id} est l’ID de l’annuaire (locataire) de l’application web.
   • client_id={web-app-calls-web-api_application_client_id}, et session_state={web-app-calls-web-api_application_client_id} est l’ID d’application (client) dans le volet Vue d’ensemble de l’application web (web-app-calls-web-api).
   • api://{web_API_application_client_id}/Forecast.Read est l’ID d’application (client) dans le volet Vue d’ensemble de l’API web (NewWebAPI1).
   • code={authorization_code} est le code d’autorisation qui a été reçu dans Demander un code d’autorisation. Celui-ci permet à l’outil cURL de demander un jeton d’accès.
   • client_secret={client_secret} est la Valeur de clé secrète client enregistrée dans Ajouter une clé secrète client.

2. Exécutez la commande cURL. Si elle a été entrée correctement, vous devez recevoir une réponse JSON similaire à la sortie suivante :

   {
      "token_type": "Bearer",
      "scope": "api://{web_API_application_client_id}/Forecast.Read",
      "expires_in": 3600,
      "ext_expires_in": 3600,
      "access_token": "{access_token}"
   }
   

Appeler l’API web avec le jeton d’accès

En exécutant la commande cURL précédente, la plateforme d'identités Microsoft a fourni un jeton d’accès. Le jeton acquis peut maintenant servir de jeton du porteur dans une requête HTTP pour appeler l’API web.

1. Pour appeler l’API web, copiez la commande cURL suivante, remplacez les valeurs suivantes entre parenthèses, puis collez le tout dans votre terminal :

   curl -X GET https://localhost:{port}/weatherforecast -ki \
   -H 'Content-Type: application/json' \
   -H "Authorization: Bearer {access_token}"
   

   • {access_token} valeur de jeton d’accès enregistrée à partir de la sortie JSON de la section précédente.
   • {port} numéro de port de l’API web enregistré lors de l’exécution de l’API dans le terminal. Vérifiez qu’il s’agit bien du numéro de port https.

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

   HTTP/2 200
   content-type: application/json; charset=utf-8
   date: Day, DD Month YYYY HH:MM:SS
   server: Kestrel
   [{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":36,"summary":"Hot","temperatureF":96},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":43,"summary":"Warm","temperatureF":109},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":18,"summary":"Warm","temperatureF":64},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":50,"summary":"Chilly","temperatureF":121},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":3,"summary":"Bracing","temperatureF":37}]
   

Étapes suivantes

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

• Plateforme d’identités Microsoft et flux de code d’autorisation OAuth
• Types d’application pour la plateforme d’identité Microsoft