Utiliser les API Microsoft Defender pour point de terminaison

S’applique à :

• Microsoft Defender pour point de terminaison Plan 1
• Microsoft Defender pour point de terminaison Plan 2
• Microsoft Defender pour les PME

Importante

Les fonctionnalités de repérage avancées ne sont pas incluses dans Defender pour les entreprises.

Vous voulez découvrir Microsoft Defender pour point de terminaison ? Inscrivez-vous pour bénéficier d’un essai gratuit.

Remarque

Si vous êtes un client du gouvernement des États-Unis, utilisez les URI répertoriés dans Microsoft Defender pour point de terminaison pour les clients du gouvernement des États-Unis.

Conseil

Pour de meilleures performances, vous pouvez utiliser le serveur plus près de votre emplacement géographique :

• us.api.security.microsoft.com
• eu.api.security.microsoft.com
• uk.api.security.microsoft.com
• au.api.security.microsoft.com
• swa.api.security.microsoft.com

Cette page explique comment créer une application pour obtenir l’accès par programmation à Defender pour point de terminaison pour le compte d’un utilisateur.

Si vous avez besoin d’un accès par programmation Microsoft Defender pour point de terminaison sans utilisateur, reportez-vous à Microsoft Defender pour point de terminaison d’accès avec le contexte de l’application.

Si vous n’êtes pas certain de l’accès dont vous avez besoin, lisez la page Introduction.

Microsoft Defender pour point de terminaison expose la plupart de ses données et actions via un ensemble d’API programmatiques. Ces API vous permettent d’automatiser les flux de travail et d’innover en fonction des fonctionnalités Microsoft Defender pour point de terminaison. L’accès à l’API nécessite l’authentification OAuth2.0. Pour plus d’informations, consultez Flux de code d’autorisation OAuth 2.0.

En général, vous devez effectuer les étapes suivantes pour utiliser les API :

• Créer une application Microsoft Entra
• Obtenir un jeton d’accès à l’aide de cette application
• Utiliser le jeton pour accéder à l’API Defender pour point de terminaison

Cette page explique comment créer une application Microsoft Entra, obtenir un jeton d’accès pour Microsoft Defender pour point de terminaison et valider le jeton.

Remarque

Lorsque vous accédez à Microsoft Defender pour point de terminaison’API pour le compte d’un utilisateur, vous avez besoin de l’autorisation d’application et de l’autorisation utilisateur appropriées. Si vous n’êtes pas familiarisé avec les autorisations utilisateur sur Microsoft Defender pour point de terminaison, consultez Gérer l’accès au portail à l’aide du contrôle d’accès en fonction du rôle.

Conseil

Si vous avez l’autorisation d’effectuer une action dans le portail, vous avez l’autorisation d’effectuer l’action dans l’API.

Créer une application

1. Connectez-vous à Azure avec un compte d’utilisateur doté du rôle Administrateur général .

2. Accédez à Microsoft Entra ID>inscriptions d'applications>Nouvelle inscription.

   

3. Lorsque la page Inscrire une application s’affiche, saisissez les informations d’inscription de votre application :

   • Nom : saisissez un nom d’application cohérent qui s’affichera pour les utilisateurs de l’application.

   • Types de compte pris en charge : sélectionnez les comptes à prendre en charge par l’application.

     
     

     Types de comptes pris en charge	Description
     Comptes dans cet annuaire organisationnel uniquement	Sélectionnez cette option si vous générez une application métier. Cette option n’est pas disponible si vous n’inscrivez pas l’application dans un annuaire. Cette option correspond à Microsoft Entra monolocataire uniquement. Il s’agit de l’option par défaut, sauf si vous inscrivez l’application hors d’un annuaire. Dans les cas où l’application est inscrite en dehors d’un annuaire, la valeur par défaut est Microsoft Entra comptes Microsoft multilocataires et personnels.
     Comptes dans un annuaire organisationnel	Sélectionnez cette option si vous souhaitez cibler tous les clients professionnels et éducatifs. Cette option correspond à un Microsoft Entra multilocataire uniquement. Si vous avez inscrit l’application comme Microsoft Entra monolocataire uniquement, vous pouvez la mettre à jour pour qu’elle soit Microsoft Entra multilocataire et revenir à monolocataire via le panneau Authentification.
     Comptes dans un annuaire organisationnel et comptes personnels Microsoft	Sélectionnez cette option pour cibler l’ensemble le plus large de clients. Cette option correspond à Microsoft Entra comptes Microsoft multilocataires et personnels. Si vous avez inscrit l’application comme Microsoft Entra comptes Microsoft multilocataires et personnels, vous ne pouvez pas le modifier dans l’interface utilisateur. Vous devez utiliser l’éditeur de manifeste de l’application pour modifier les types de compte pris en charge.

   • URI de redirection (facultatif) : sélectionnez le type d’application que vous créez, Web ou Client public (mobile et bureau), puis entrez l’URI de redirection (ou URL de réponse).

     • Pour les applications web, indiquez l’URL de base de votre application. Par exemple, http://localhost:31544 peut être l’URL d’une application web en cours d’exécution sur votre ordinateur local. Les utilisateurs peuvent utiliser cette URL pour se connecter à une application web cliente.

     • Pour les applications clientes publiques, fournissez l’URI utilisé par Microsoft Entra ID pour retourner des réponses de jeton. Entrez une valeur spécifique de votre application, par exemple, myapp://auth.

     Pour accéder à des exemples spécifiques aux applications web ou natives, consultez les Guides de démarrage rapides.

     Lorsque vous avez terminé, sélectionnez Inscrire.

4. Autorisez votre application à accéder à Microsoft Defender pour point de terminaison et attribuez-lui l’autorisation « Lire les alertes » :

   • Dans la page de votre application, sélectionnez Api Autorisations> Ajouter des API d’autorisation>que mon organization utilise> le type WindowsDefenderATP, puis sélectionnez WindowsDefenderATP.

     Remarque

     WindowsDefenderATP n’apparaît pas dans la liste d’origine. Commencez à écrire son nom dans la zone de texte pour le voir apparaître.

     

   • Choisissez Autorisations> déléguéesAlerte.Lire>, sélectionnez Ajouter des autorisations.

     

   Importante

   Sélectionnez les autorisations appropriées. Les alertes de lecture n’en sont qu’un exemple.

   Par exemple :

   • Pour exécuter des requêtes avancées, sélectionnez l’autorisation Exécuter les requêtes avancées .

   • Pour isoler un appareil, sélectionnez Isoler l’autorisation de l’ordinateur .

   • Pour déterminer l’autorisation dont vous avez besoin, consultez la section Autorisations dans l’API que vous souhaitez appeler.

   • Sélectionnez Accorder le consentement.

     Remarque

     Chaque fois que vous ajoutez une autorisation, vous devez sélectionner Accorder le consentement pour que la nouvelle autorisation prenne effet.

     

5. Notez votre ID d’application et votre ID de locataire.

   Dans la page de votre application, accédez à Vue d’ensemble et copiez les informations suivantes :

   

Obtenir un jeton d’accès

Pour plus d’informations sur les jetons Microsoft Entra, consultez Microsoft Entra tutoriel.

Utilisation de C#

• Copiez/collez la classe ci-dessous dans votre application.

• Utilisez la méthode AcquireUserTokenAsync avec votre ID d’application, id de locataire, nom d’utilisateur et mot de passe pour acquérir un jeton.

  namespace WindowsDefenderATP
  {
      using System.Net.Http;
      using System.Text;
      using System.Threading.Tasks;
      using Newtonsoft.Json.Linq;
  
      public static class WindowsDefenderATPUtils
      {
          private const string Authority = "https://login.microsoftonline.com";
  
          private const string WdatpResourceId = "https://api.securitycenter.microsoft.com";
  
          public static async Task<string> AcquireUserTokenAsync(string username, string password, string appId, string tenantId)
          {
              using (var httpClient = new HttpClient())
              {
                  var urlEncodedBody = $"resource={WdatpResourceId}&client_id={appId}&grant_type=password&username={username}&password={password}";
  
                  var stringContent = new StringContent(urlEncodedBody, Encoding.UTF8, "application/x-www-form-urlencoded");
  
                  using (var response = await httpClient.PostAsync($"{Authority}/{tenantId}/oauth2/token", stringContent).ConfigureAwait(false))
                  {
                      response.EnsureSuccessStatusCode();
  
                      var json = await response.Content.ReadAsStringAsync().ConfigureAwait(false);
  
                      var jObject = JObject.Parse(json);
  
                      return jObject["access_token"].Value<string>();
                  }
              }
          }
      }
  }
  

Valider le jeton

Vérifiez que vous avez un jeton correct :

• Copiez/collez dans JWT le jeton que vous avez obtenu à l’étape précédente afin de le décoder.

• Vérifiez que vous obtenez une revendication « scp » avec les autorisations d’application souhaitées.

• Dans la capture d’écran ci-dessous, vous pouvez voir un jeton décodé acquis à partir de l’application dans le tutoriel :

  

Utiliser le jeton pour accéder à Microsoft Defender pour point de terminaison’API

• Choisissez l’API que vous souhaitez utiliser - API Microsoft Defender pour point de terminaison prises en charge.

• Définissez l’en-tête d’autorisation dans la requête HTTP que vous envoyez à « Porteur {token} » (le porteur est le schéma d’autorisation).

• La durée d’expiration du jeton est de 1 heure (vous pouvez envoyer plusieurs requêtes avec le même jeton).

• Exemple d’envoi d’une demande pour obtenir une liste d’alertes à l’aide de C# :

  var httpClient = new HttpClient();
  
  var request = new HttpRequestMessage(HttpMethod.Get, "https://api.securitycenter.microsoft.com/api/alerts");
  
  request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
  
  var response = httpClient.SendAsync(request).GetAwaiter().GetResult();
  
  // Do something useful with the response
  

Voir aussi

• API Microsoft Defender pour point de terminaison
• Accéder Microsoft Defender pour point de terminaison avec le contexte de l’application

Conseil

Voulez-vous en savoir plus ? Engage avec la communauté Microsoft Security dans notre communauté technique : Microsoft Defender pour point de terminaison Tech Community.