Appeler une API dans votre application démon Node.js

Article
04/25/2024

Ce guide utilise un exemple d’application démon Node.js pour vous montrer comment une application démon acquiert un jeton pour appeler une API web. Microsoft Entra protège l’API web.

Une application démon peut acquérir un jeton pour appeler une API web pour son propre compte (pas pour le compte d’un utilisateur). Les utilisateurs ne peuvent pas interagir avec une application démon, car elle nécessite sa propre identité. Ce type d’application demande un jeton d’accès en utilisant son identité d’application et en présentant à ID externe son ID d’application, ses informations d’identification (mot de passe ou certificat) et un URI d’ID d’application.

Une application démon utilise l’octroi d’informations d’identification du client OAuth 2.0 standard. Pour simplifier le processus d’acquisition du jeton, l’exemple que nous utilisons dans cet article utilise la bibliothèque d’authentification Microsoft pour Node (MSAL Node).

Prérequis

Visual Studio Code ou un autre éditeur de code.
Node.js.
.NET 7.0 ou version ultérieure.
Un locataire externe. Si vous n’en avez pas, inscrivez-vous pour obtenir un essai gratuit.

Inscrire une application démon et une API web

Au cours de cette étape, vous créez le démon et les inscriptions d'applications d'API web, et vous spécifiez les champs d'application de votre API web.

Inscrire une application d’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 votre tenant externe depuis le menu Répertoires + abonnements.
Accédez à Identité>Applications>Inscriptions d’applications.
Sélectionnez + Nouvelle inscription.
Dans la page Inscrire une application qui s’affiche, entrez les informations relatives à l’inscription de votre application :
1. Dans la section Nom, entrez un nom d’application significatif qui s’affiche pour les utilisateurs de l’application, par exemple, ciam-ToDoList-api.
2. Sous Types de comptes pris en charge, sélectionnez Comptes dans cet annuaire organisationnel uniquement.
Sélectionnez Inscrire pour créer l’application.
Le Vue d’ensemble de l’application s’affiche une fois l’inscription terminée. Enregistrez l’ID du répertoire (locataire) et l’ID d’application (client) à utiliser dans le code source de votre application.

Configurer les rôles d’application

Une API doit publier au moins un rôle d’application pour les applications, également appelé Autorisation d’application, pour que les applications clientes obtiennent un jeton d’accès en leur nom. Les autorisations d’application sont le type d’autorisations que les API doivent publier lorsqu’elles souhaitent permettre aux applications clientes de s’authentifier correctement en tant qu’elles-mêmes et qu’elles n’ont pas besoin de connecter des utilisateurs. Pour publier une autorisation d'application, procédez comme suit :

Dans la page Inscriptions d’applications, sélectionnez l’application que vous avez créée (par exemple, ciam-ToDoList-api) pour ouvrir sa page Vue d’ensemble.
Sous Gérer, sélectionnez Rôles d’applications.

Sélectionnez Créer un rôle d'application, puis saisissez les valeurs suivantes, puis sélectionnez Appliquer pour enregistrer vos modifications :

Propriété	Value
Nom complet	ToDoList.Read.All
Types de membres autorisés	Applications
Valeur	ToDoList.Read.All
Description	Autoriser l'application à lire la liste de tâches de chaque utilisateur à l'aide de 'TodoListApi'

Sélectionnez à nouveau Créer un rôle d'application, puis saisissez les valeurs suivantes pour le deuxième rôle d'application, puis sélectionnez Appliquer pour enregistrer vos modifications :

Propriété	Value
Nom complet	ToDoList.ReadWrite.All
Types de membres autorisés	Applications
Valeur	ToDoList.ReadWrite.All
Description	Autoriser l’application à lire et écrire la liste ToDo de chaque utilisateur à l’aide de « TodoListApi »

Configurer des revendications facultatives

Les jetons renvoyés par l'identité Microsoft sont plus petits pour garantir des performances optimales aux clients qui les demandent. Par conséquent, plusieurs réclamations ne sont plus présentes dans le jeton par défaut et doivent être demandées spécifiquement pour chaque application. Pour cette application, vous incluez la revendication facultative idtyp pour aider l’API web à déterminer s’il s’agit d’un jeton d’application ou d’un jeton d’application+utilisateur. Même si vous pouvez utiliser une combinaison de revendications scp et roles dans le même but, l’utilisation de la revendication idtyp est le moyen le plus simple de distinguer un jeton d’application d’un jeton d’application+utilisateur. Par exemple, la valeur de cette revendication est app lorsque le jeton est un jeton d'application uniquement.

Utilisez les étapes suivantes pour configurer la revendication facultative idtyp :

À partir de la page Inscriptions d’applications, pour laquelle vous voulez configurer une revendication facultative, comme ciam-client-app, ouvrez sa page Vue d’ensemble.
Dans Gérer, sélectionnez Configuration de jetons.
Sélectionnez Ajouter une revendication facultative.
Sous Type de jeton, choisissez Accès.
Sélectionnez l’idtyp de revendication facultatif.
Sélectionnez Ajouter pour enregistrer vos changements.

Enregistrer l'application démon

Pour permettre à votre application de connecter des utilisateurs avec Microsoft Entra, lD externe Microsoft Entra doit être informé de l’existence de l’application que vous créez. L’inscription d’application établit une relation de confiance entre l’application et Microsoft Entra. Lorsque vous enregistrez une application, l'ID externe génère un identifiant unique appelé ID d'application (client), une valeur utilisée pour identifier votre application lors de la création de demandes d'authentification.

Les étapes suivantes vous montrent comment inscrire votre application dans le centre d’administration Microsoft Entra :

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 votre tenant externe depuis le menu Répertoires + abonnements.
Accédez à Identité>Applications>Inscriptions d’applications.
Sélectionnez + Nouvelle inscription.
Dans la page Inscrire une application qui s’affiche ;
1. Dans Nom, entrez un nom d’application explicite qui va être présenté aux utilisateurs de l’application, par exemple ciam-client-app.
2. Sous Types de comptes pris en charge, sélectionnez Comptes dans cet annuaire organisationnel uniquement.
Sélectionnez Inscription.
Le volet Vue d’ensemble de l’application s’affiche après une inscription réussie. Enregistrez l’ID d’application (client) à utiliser dans le code source de votre application.

Créer une clé secrète client

Créez un secret client pour l’application inscrite. L’application utilise la clé secrète client pour prouver son identité quand elle demande des jetons.

Dans la page inscriptions d’applications, sélectionnez l’application que vous avez créée (par exemple, ciam-client-app) pour ouvrir sa page Vue d’ensemble.
Sous Gérer, sélectionnez Certificats et secrets.
Sélectionnez Nouveau secret client.
Entrez une description pour la clé secrète client dans la zone Description (par exemple clé secrète client ciam).
Sous Expire, sélectionnez la durée de validité de la clé secrète (en fonction des règles de sécurité de votre organisation), puis sélectionnez Ajouter.
Enregistrez la Valeur du secret. Vous utiliserez cette valeur pour la configuration dans une étape ultérieure. La valeur du secret ne sera plus affichée et sera irrécupérable une fois que vous quittez les Certificats et secrets. Veillez à l’enregistrer.

Accorder des autorisations d’API à l’application démon

Dans la page Inscriptions d’applications, sélectionnez l’application que vous avez créée, par exemple, ciam-client-app.
Sous Gérer, sélectionnez Autorisations de l’API.
Sous Autorisations configurées, sélectionnez Ajouter une autorisation.
Sélectionnez l’onglet API utilisées par mon organisation.
Dans la liste des API, sélectionnez l’API, par exemple ciam-ToDoList-api.
Sélectionnez l’option Autorisations de l’application. Nous sélectionnons cette option car l’application se connecte en tant qu’elle-même, et non en tant qu’utilisateur.
Dans la liste des autorisations, sélectionnez TodoList.Read.All, ToDoList.ReadWrite.All (utilisez la zone de recherche si nécessaire).
Sélectionnez le bouton Ajouter des autorisations.
À ce stade, vous avez attribué les autorisations correctement. Toutefois, étant donné que l’application démon ne permet pas aux utilisateurs d’interagir avec elle, les utilisateurs eux-mêmes ne peuvent pas consentir à ces autorisations. Pour résoudre ce problème, en tant qu’administrateur, vous devez consentir à ces autorisations au nom de tous les utilisateurs du locataire :
1. Sélectionnez Accorder le consentement administrateur pour <nom de votre locataire>, puis sélectionnez Oui.
2. Sélectionnez Actualiser, puis vérifiez que Accordé pour <nom de votre locataire> s’affiche sous État pour les deux autorisations.

Cloner ou télécharger un exemple d’application démon et d’API web

Pour obtenir l’exemple d’application, vous pouvez le cloner à partir de GitHub ou le télécharger sous la forme d’un fichier .zip.

Pour cloner l’exemple, ouvrez une invite de commandes, accédez à l’emplacement où vous souhaitez créer le projet, puis entrez la commande suivante :
```
git clone https://github.com/Azure-Samples/ms-identity-ciam-javascript-tutorial.git
```
Téléchargez le fichier .zip. Extrayez-la dans un chemin d’accès de fichier où la longueur du nom est inférieure à 260 caractères.

Installer les dépendances du projet

Ouvrez une fenêtre de console et accédez au répertoire qui contient l’exemple d’application Node.js :
```
cd 2-Authorization\3-call-api-node-daemon\App
```
Exécutez les commandes suivantes pour installer les dépendances d’applications :
```
npm install && npm update
```

Configurer l’exemple d’application démon et d’API

Pour utiliser l’inscription de votre application dans l’exemple d’application web cliente :

Dans votre éditeur de code, ouvrez le fichier App\authConfig.js.
Recherchez l’espace réservé :
- Enter_the_Application_Id_Here et remplacez-le par l’ID d’application (client) de l’application démon inscrite précédemment.
- Enter_the_Tenant_Subdomain_Here et remplacez par le sous-domaine du répertoire (locataire). Par exemple, si votre domaine principal du locataire est contoso.onmicrosoft.com, utilisez contoso. Si vous ne disposez pas du nom de votre locataire, découvrez de quelle manière consulter les détails de votre locataire.
- Enter_the_Client_Secret_Here et remplacez-le par la valeur de secret d’application démon que vous avez copiée précédemment.
- Enter_the_Web_Api_Application_Id_Here avec l’ID d’application (client) de l’application API web, copiée précédemment.

Pour utiliser l’inscription de votre application dans l’exemple d’API web :

Dans votre éditeur de code, ouvrez le fichier API\ToDoListAPI\appsettings.json.
Recherchez l’espace réservé :
- Enter_the_Application_Id_Here avec l’ID d’application (client) de l’application API web, copiée précédemment.
- Enter_the_Tenant_Id_Here et remplacez-le par l’ID de répertoire (locataire) que vous avez copié précédemment.
- Enter_the_Tenant_Subdomain_Here et remplacez par le sous-domaine du répertoire (locataire). Par exemple, si votre domaine principal du locataire est contoso.onmicrosoft.com, utilisez contoso. Si vous ne disposez pas du nom de votre locataire, découvrez de quelle manière consulter les détails de votre locataire.

Exécuter et tester l’exemple d’application démon et d’API

Ouvrez une fenêtre de console, puis exécutez l’API web à l’aide des commandes suivantes :
```
cd 2-Authorization\3-call-api-node-daemon\API\ToDoListAPI
dotnet run
```
Exécutez le client d’application web à l’aide des commandes suivantes :
```
2-Authorization\3-call-api-node-daemon\App
node . --op getToDos
```

Si votre application démon et votre API web s’exécutent correctement, vous devriez voir quelque chose de similaire au tableau JSON suivant dans votre fenêtre de console

{
    "id": 1,
    "owner": "3e8....-db63-43a2-a767-5d7db...",
    "description": "Pick up grocery"
},
{
    "id": 2,
    "owner": "c3cc....-c4ec-4531-a197-cb919ed.....",
    "description": "Finish invoice report"
},
{
    "id": 3,
    "owner": "a35e....-3b8a-4632-8c4f-ffb840d.....",
    "description": "Water plants"
}

Fonctionnement

L’application Node.js utilise l’octroi d’informations d’identification du client OAuth 2.0 pour acquérir un jeton d’accès pour elle-même et non pour l’utilisateur. Le jeton d’accès que l’application demande contient les autorisations représentées en tant que rôles. Le flux d’informations d’identification client utilise cet ensemble d’autorisations au lieu des étendues d’utilisateur pour les jetons d’application. Vous avez exposé ces autorisations d’application dans l’API web précédemment, puis vous les avez accordées à l’application démon.

Côté API, l’API web doit vérifier que le jeton d’accès dispose des autorisations requises (autorisations d’application). L’API web ne peut pas accepter un jeton d’accès qui ne dispose pas des autorisations requises.

Accès aux données

Un point de terminaison d’API web doit être prêt à accepter les appels d’utilisateurs et d’applications. Par conséquent, il doit avoir un moyen de répondre à chaque demande en conséquence. Par exemple, un appel d’un utilisateur via des autorisations/étendues déléguées reçoit la liste de tâches des données de l’utilisateur. En revanche, un appel d’une application via des autorisations/rôles d’application peut recevoir l’intégralité de la liste de tâches. Toutefois, dans cet article, nous n’effectuons qu’un appel d’application. Nous n’avons donc pas eu besoin de configurer des autorisations/étendues déléguées.