Appeler une API web ASP.NET Core avec cURL

Prérequis

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.

Enregistrer 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 :

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 (client) et l’ID d’application (client) à utiliser dans les étapes suivantes.

Ajouter une clé secrète 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>Nouvelle clé secrète 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>API utilisées par mon organisation.
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.

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 du répertoire (client) 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 client 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 :

   • Bash
   • Invite de commandes Windows

   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 du répertoire (client) 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} la valeur de jeton d’accès enregistrée à partir de la sortie JSON de la section précédente.
   • {port} le 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 2.0
• Types d’application pour la plateforme d’identité Microsoft