Partager via


Démarrage rapide : Appeler une API web dans un exemple d’application démon

S’applique à : cercle vert avec un symbole de coche blanc qui indique que le contenu suivant s’applique aux locataires du personnel. Cercle vert des locataires de main-d’œuvre avec un symbole de coche blanche qui indique que le contenu suivant s’applique aux locataires externes. Locataires externes (en savoir plus)

Dans ce guide de démarrage rapide, vous utilisez un exemple d’application démon pour acquérir un jeton d’accès et appeler une API web protégée à l’aide de la bibliothèque d’authentification Microsoft (MSAL).

Avant de commencer, utilisez le sélecteur Choisir un type de locataire en haut de cette page pour sélectionner le type de locataire. Microsoft Entra ID fournit deux configurations de locataire, la main-d’œuvre et l’externe. Une configuration de locataire de main-d’œuvre concerne vos employés, vos applications internes et d’autres ressources organisationnelles. Un locataire externe est destiné à vos applications orientées client.

L’exemple d’application que vous utilisez dans ce guide de démarrage rapide acquiert un jeton d’accès pour appeler l’API Microsoft Graph.

Prerequisites

  • Un compte Azure avec un abonnement actif. Si vous n’en avez pas encore, créez un compte gratuitement.
  • Ce compte Azure doit disposer d’autorisations pour gérer les applications. Les rôles Microsoft Entra suivants incluent les autorisations requises :
    • Administrateur d’application
    • Développeur d’applications
    • Administrateur d’applications cloud
  • Un locataire de main-d’œuvre. Vous pouvez utiliser votre répertoire par défaut ou configurer un nouveau locataire.
  • Inscrivez une nouvelle application dans le Centre d’administration Microsoft Entra, configurée pour les comptes dans cet annuaire organisationnel uniquement. Pour plus d’informations, reportez-vous à l’inscription d’une application . Enregistrez les valeurs suivantes à partir de la page Vue d’ensemble de l’application pour une utilisation ultérieure :
    • ID d’application (client)
    • ID de l’annuaire (locataire)
  • Ajoutez une clé secrète client à votre inscription d’application. N’utilisez pas les secrets client dans les applications de production. Utilisez plutôt des certificats ou des informations d’identification fédérées. Pour plus d’informations, consultez ajouter des informations d’identification à votre application.

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

Pour que l’application démon accède aux données dans l’API Microsoft Graph, vous lui accordez les autorisations dont elle a besoin. L’application démon a besoin d’autorisations de type d’application. Les utilisateurs ne peuvent pas interagir avec une application démon, de sorte que l’administrateur du locataire doit donner son consentement à ces autorisations. Procédez comme suit pour accorder et donner votre consentement aux autorisations :

Pour l’application démon .NET, vous n’avez pas besoin d’accorder et de donner votre consentement à une autorisation. Cette application démon lit ses propres informations d’inscription d’application, de sorte qu’elle peut le faire sans disposer d’autorisations d’application.

Cloner ou télécharger l’exemple d’application

Pour obtenir l’exemple d’application, vous pouvez le cloner à partir de GitHub ou le télécharger en tant que fichier .zip .

  • Pour cloner l’exemple, ouvrez une invite de commandes et 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-docs-code-dotnet.git

Configurer le projet

Pour utiliser les détails de l’inscription de votre application dans l’exemple d’application démon client, procédez comme suit :

  1. Ouvrez une fenêtre de console, puis accédez au répertoire ms-identity-docs-code-dotnet/console-daemon :

    cd ms-identity-docs-code-dotnet/console-daemon
    
  2. Ouvrez Program.cs et remplacez le contenu du fichier par l’extrait de code suivant ;

     // Full directory URL, in the form of https://login.microsoftonline.com/<tenant_id>
     Authority = " https://login.microsoftonline.com/Enter_the_tenant_ID_obtained_from_the_Microsoft_Entra_admin_center",
     // 'Enter the client ID obtained from the Microsoft Entra admin center
     ClientId = "Enter the client ID obtained from the Microsoft Entra admin center",
     // Client secret 'Value' (not its ID) from 'Client secrets' in the Microsoft Entra admin center
     ClientSecret = "Enter the client secret value obtained from the Microsoft Entra admin center",
     // Client 'Object ID' of app registration in Microsoft Entra admin center - this value is a GUID
     ClientObjectId = "Enter the client Object ID obtained from the Microsoft Entra admin center"
    
    • Authority - L’autorité est une URL qui indique un répertoire à partir duquel MSAL peut demander des jetons. Remplacez Enter_the_tenant_ID_obtained_from_the_Microsoft_Entra_admin_center par la valeur d’ID d’annuaire (locataire) enregistrée précédemment.
    • ClientId - Identificateur de l’application, également appelé client. Remplacez le texte entre guillemets par la Application (client) ID valeur enregistrée précédemment à partir de la page vue d’ensemble de l’application inscrite.
    • ClientSecret - Clé secrète client créée pour l’application dans le Centre d’administration Microsoft Entra. Entrez la valeur de la clé secrète client.
    • ClientObjectId - ID d’objet de l’application cliente. Remplacez le texte entre guillemets par la Object ID valeur que vous avez enregistrée précédemment à partir de la page vue d’ensemble de l’application inscrite.

Exécuter et tester l’application

Vous avez configuré votre exemple d’application. Vous pouvez continuer à l’exécuter et à le tester.

À partir de votre fenêtre de console, exécutez la commande suivante pour générer et exécuter l’application :

dotnet run

Une fois l’application exécutée avec succès, elle affiche une réponse similaire à l’extrait de code suivant (raccourcie pour la concision) :

{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#applications/$entity",
"id": "00001111-aaaa-2222-bbbb-3333cccc4444",
"deletedDateTime": null,
"appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
"applicationTemplateId": null,
"disabledByMicrosoftStatus": null,
"createdDateTime": "2021-01-17T15:30:55Z",
"displayName": "identity-dotnet-console-app",
"description": null,
"groupMembershipClaims": null,
...
}

Fonctionnement

Une application démon acquiert un jeton pour le compte de lui-même (et non pour le compte d’un utilisateur). Les utilisateurs ne peuvent pas interagir avec une application démon, car il nécessite sa propre identité. Ce type d’application demande un jeton d’accès à l’aide de son identité d’application en présentant son ID d’application, ses informations d’identification (secret ou certificat) et un URI d’ID d’application. L’application démon utilise le flux d’octroi d’informations d’identification du client OAuth 2.0 standard pour acquérir un jeton d’accès.

L’application acquiert un jeton d’accès à partir de la plateforme d’identités Microsoft. Le jeton d’accès est étendu pour l’API Microsoft Graph. L’application utilise ensuite le jeton d’accès pour demander ses propres détails d’inscription d’application auprès de l’API Microsoft Graph. L’application peut demander n’importe quelle ressource de l’API Microsoft Graph tant que le jeton d’accès dispose des autorisations appropriées.

L’exemple montre comment un travail sans assistance ou un service Windows peut s’exécuter avec une identité d’application, au lieu de l’identité d’un utilisateur.

Prerequisites

  • Un compte Azure avec un abonnement actif. Si vous n’en avez pas encore, créez un compte gratuitement.
  • Ce compte Azure doit disposer d’autorisations pour gérer les applications. Les rôles Microsoft Entra suivants incluent les autorisations requises :
    • Administrateur d’application
    • Développeur d’applications
    • Administrateur d’applications cloud
  • Un locataire externe. Pour en créer un, choisissez parmi les méthodes suivantes :
  • Inscrivez une nouvelle application dans le Centre d’administration Microsoft Entra avec la configuration suivante. Pour plus d’informations, consultez Inscrire une application.
    • Nom : ciam-daemon-app
    • Types de comptes pris en charge : comptes dans cet annuaire organisationnel uniquement (locataire unique)
  • Visual Studio Code ou un autre éditeur de code.
  • .NET 7.0 ou version ultérieure.
  • Node.js (pour l’implémentation de Node uniquement)

Créer une clé secrète client

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

  1. Dans la page Inscriptions d’applications , sélectionnez l’application que vous avez créée (par exemple, la clé secrète client d’application web) pour ouvrir sa page Vue d’ensemble .
  2. Sous Gérer, sélectionnez Certificats et secrets>clés secrètes> clientNouveau secret client.
  3. Dans la zone Description , entrez une description pour la clé secrète client (par exemple, clé secrète client d’application web).
  4. Sous Expire, sélectionnez une durée pendant laquelle le secret est valide (conformément aux règles de sécurité de votre organisation), puis sélectionnez Ajouter.
  5. Enregistrez la valeur du secret. Vous utilisez cette valeur pour la configuration dans une étape ultérieure. La valeur du secret ne sera plus affichée et n’est récupérable par aucun moyen, une fois que vous vous éloignez des certificats et des secrets. Veillez à l’enregistrer.

Lorsque vous créez des informations d’identification pour une application cliente confidentielle :

  • Microsoft vous recommande d’utiliser un certificat au lieu d’un secret client avant de déplacer l’application vers un environnement de production. Pour plus d’informations sur l’utilisation d’un certificat, consultez les instructions des informations d’identification du certificat d’authentification d’application de la plateforme d’identités Microsoft.

  • À des fins de test, vous pouvez créer un certificat auto-signé et configurer vos applications pour qu’elles s’authentifient. Toutefois, en production, vous devez acheter un certificat signé par une autorité de certification connue, puis utiliser Azure Key Vault pour gérer l’accès aux certificats et la durée de vie.

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

  1. Dans la page Inscriptions d’applications , sélectionnez l’application que vous avez créée, telle que ciam-client-app.

  2. Sous Gérer, sélectionnez Autorisations de l’API.

  3. Sous Autorisations configurées, sélectionnez Ajouter une autorisation.

  4. Sélectionnez les API que mon organisation utilise l’onglet.

  5. Dans la liste des API, sélectionnez l’API telle que ciam-ToDoList-api.

  6. Sélectionnez l’option Autorisations d’application . Nous sélectionnons cette option en tant que connexion de l’application elle-même, mais pas au nom d’un utilisateur.

  7. Dans la liste des autorisations, sélectionnez TodoList.Read.All, ToDoList.ReadWrite.All (utilisez la zone de recherche si nécessaire).

  8. Sélectionnez le bouton Ajouter des autorisations .

  9. À ce stade, vous avez attribué les autorisations correctement. Toutefois, étant donné que l’application démon ne permet pas aux utilisateurs d’interagir avec lui, les utilisateurs eux-mêmes ne peuvent pas consentir à ces autorisations. Pour résoudre ce problème, comme l’administrateur doit donner son consentement à ces autorisations pour le compte de tous les utilisateurs du locataire :

    1. Sélectionnez Accorder le consentement administrateur pour <le nom> de votre locataire, puis sélectionnez Oui.
    2. Sélectionnez Actualiser, puis vérifiez que le nom accordé pour <votre locataire> apparaît sous État pour les deux autorisations.

Configurer des rôles d’application

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

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

  2. Sous Gérer, sélectionnez Rôles d’application.

  3. Sélectionnez Créer un rôle d’application, entrez les valeurs suivantes, puis sélectionnez Appliquer pour enregistrer vos modifications :

    Propriété Valeur
    Nom affiché ToDoList.Read.All
    Types de membres autorisés Applications
    Valeur ToDoList.Read.All
    Descriptif Autoriser l’application à lire la liste ToDo de chaque utilisateur à l’aide de « TodoListApi »
    Voulez-vous activer ce rôle d’application ? Maintenez cette option cochée
  4. Sélectionnez à nouveau Créer un rôle d’application , puis entrez les valeurs suivantes pour le deuxième rôle d’application, puis sélectionnez Appliquer pour enregistrer vos modifications :

    Propriété Valeur
    Nom affiché ToDoList.ReadWrite.All
    Types de membres autorisés Applications
    Valeur ToDoList.ReadWrite.All
    Descriptif Autoriser l’application à lire et écrire la liste ToDo de chaque utilisateur à l’aide de « ToDoListApi »
    Voulez-vous activer ce rôle d’application ? Maintenez cette option cochée

Configurer des revendications facultatives

Vous pouvez ajouter la revendication facultative idtyp pour aider l’API web à déterminer si un jeton est un jeton d’application ou une application + jeton utilisateur . Bien que vous puissiez utiliser une combinaison de revendications scp et de rôles dans le même but, l’utilisation de la revendication idtyp est le moyen le plus simple d’indiquer un jeton d’application et un jeton d’utilisateur + application + jeton utilisateur séparé. Par exemple, la valeur de cette revendication est l’application lorsque le jeton est un jeton d’application uniquement.

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 en tant que fichier .zip.

  • Pour cloner l’exemple, ouvrez une invite de commandes et 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
    
  • Vous pouvez également télécharger les exemples .zip fichier, puis l’extraire dans un chemin d’accès de fichier où la longueur du nom est inférieure à 260 caractères.

Installer les dépendances de projet

  1. 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
    
  2. Exécutez les commandes suivantes pour installer les dépendances d’application :

    npm install && npm update
    

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

Pour utiliser les détails de l’inscription de votre application dans l’exemple d’application web cliente, procédez comme suit :

  1. Dans votre éditeur de code, ouvrez App\authConfig.js le fichier.

  2. Recherchez l’espace réservé :

    • Enter_the_Application_Id_Here et remplacez-le par l’ID d’application (client) de l’application démon que vous avez inscrite précédemment.

    • Enter_the_Tenant_Subdomain_Here et remplacez-le par le sous-domaine Directory (locataire). Par exemple, si votre domaine principal de locataire est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas de nom de locataire, découvrez comment lire les détails de votre locataire.

    • Enter_the_Client_Secret_Here et remplacez-le par la valeur secrète de l’application démon que vous avez copiée précédemment.

    • Enter_the_Web_Api_Application_Id_Here et remplacez-le par l’ID d’application (client) de l’API web que vous avez copiée précédemment.

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

  1. Dans votre éditeur de code, ouvrez API\ToDoListAPI\appsettings.json le fichier.

  2. Recherchez l’espace réservé :

    • Enter_the_Application_Id_Here et remplacez-le par l’ID d’application (client) de l’API web que vous avez copiée.

    • Enter_the_Tenant_Id_Here et remplacez-le par l’ID d’annuaire (locataire) que vous avez copié précédemment.

    • Enter_the_Tenant_Subdomain_Here et remplacez-le par le sous-domaine Directory (locataire). Par exemple, si votre domaine principal de locataire est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas de nom de locataire, découvrez comment lire les détails de votre locataire.

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

Vous avez configuré votre exemple d’application. Vous pouvez continuer à l’exécuter et à le tester.

  1. 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
    
  2. 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 devez 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 le flux d’octroi d’informations d’identification du client OAuth 2.0 pour acquérir un jeton d’accès pour lui-même et non pour l’utilisateur. 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 du client utilise cet ensemble d’autorisations à la place des étendues 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, un exemple d’API web .NET, l’API 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 n’a pas les autorisations requises.

Accès aux données

Un point de terminaison d’API web doit être prêt à accepter les appels des utilisateurs et des 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 les données de l’utilisateur to-do liste. En revanche, un appel d’une application via des autorisations/rôles d’application peut recevoir l’intégralité de la liste des to-do. Toutefois, dans cet article, nous effectuons uniquement un appel d’application. Nous n’avons donc pas besoin de configurer les autorisations/étendues déléguées.