Partager via

Créer une application pour accéder aux API XDR Microsoft Defender pour le compte d’un utilisateur

  • Article

S’applique à :

  • Microsoft Defender XDR

Importante

Certaines informations ont trait à un produit préalablement publié, qui peut être modifié de manière significative avant sa publication commerciale. Microsoft n’offre aucune garantie, explicite ou implicite, concernant les informations fournies ici.

Cette page explique comment créer une application pour obtenir un accès par programmation à Microsoft Defender XDR pour le compte d’un seul utilisateur.

Si vous avez besoin d’un accès par programmation à Microsoft Defender XDR sans utilisateur défini (par exemple, si vous écrivez une application en arrière-plan ou un démon), consultez Créer une application pour accéder à Microsoft Defender XDR sans utilisateur. Si vous devez fournir l’accès à plusieurs locataires, par exemple, si vous servez une grande organisation ou un groupe de clients, consultez Créer une application avec un accès partenaire aux API Microsoft Defender XDR. Si vous ne savez pas quel type d’accès vous avez besoin, consultez Prise en main.

Microsoft Defender XDR expose la plupart de ses données et actions par le biais d’un ensemble d’API programmatiques. Ces API vous aident à automatiser les workflows et à utiliser les fonctionnalités de Microsoft Defender XDR. Cet 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 ces API :

  • Créez une application Microsoft Entra.
  • Obtenez un jeton d’accès à l’aide de cette application.
  • Utilisez le jeton pour accéder à l’API XDR Microsoft Defender.

Cet article explique comment :

  • Créer une application Microsoft Entra
  • Obtenir un jeton d’accès à Microsoft Defender XDR
  • Valider le jeton

Remarque

Lorsque vous accédez à l’API Microsoft Defender XDR pour le compte d’un utilisateur, vous avez besoin des autorisations d’application et des autorisations utilisateur appropriées.

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 en tant qu’utilisateur avec le rôle Administrateur général .

  2. Accédez à Microsoft Entra ID> Inscriptions >d’applicationsNouvelle inscription.

    Option Nouvelle inscription dans le volet Gérer du portail Azure

  3. Dans le formulaire, choisissez un nom pour votre application et entrez les informations suivantes pour l’URI de redirection, puis sélectionnez Inscrire.

    Volet d’inscription de l’application dans le portail Azure

  4. Dans la page de votre application, sélectionnez Api Autorisations> Ajouter des APId’autorisation>que mon organisation utilise>, tapez Protection Microsoft contre les menaces, puis sélectionnez Protection Microsoft contre les menaces. Votre application peut désormais accéder à Microsoft Defender XDR.

    Conseil

    Microsoft Threat Protection est un ancien nom de Microsoft Defender XDR et n’apparaîtra pas dans la liste d’origine. Vous devez commencer à écrire son nom dans la zone de texte pour le voir apparaître.

    Volet API de votre organisation dans le portail Microsoft Defender

    • Choisissez Autorisations déléguées. Choisissez les autorisations appropriées pour votre scénario (par exemple Incident.Read), puis sélectionnez Ajouter des autorisations.

      Volet Autorisations déléguées dans le portail Microsoft Defender

    Remarque

    Vous devez sélectionner les autorisations appropriées pour votre scénario. Lire tous les incidents n’est qu’un exemple. Pour déterminer l’autorisation dont vous avez besoin, consultez la section Autorisations de l’API que vous souhaitez appeler.

    Par exemple, pour exécuter des requêtes avancées, sélectionnez l’autorisation « Exécuter des requêtes avancées » ; pour isoler un appareil, sélectionnez l’autorisation « Isoler la machine ».

  5. Sélectionnez Accorder le consentement de l’administrateur. Chaque fois que vous ajoutez une autorisation, vous devez sélectionner Accorder le consentement administrateur pour qu’elle prenne effet.

    Volet d’octroi du consentement administrateur dans le portail Microsoft Defender

  6. Enregistrez votre ID d’application et votre ID de locataire dans un endroit sûr. Ils sont répertoriés sous Vue d’ensemble sur la page de votre application.

    Volet Vue d’ensemble dans le portail Microsoft Defender

Obtenir un jeton d’accès

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

Obtenir un jeton d’accès pour le compte d’un utilisateur à l’aide de PowerShell

Utilisez la bibliothèque MSAL.PS pour acquérir des jetons d’accès avec des autorisations déléguées. Exécutez les commandes suivantes pour obtenir le jeton d’accès au nom d’un utilisateur :

Install-Module -Name MSAL.PS # Install the MSAL.PS module from PowerShell Gallery

$TenantId = " " # Paste your directory (tenant) ID here.
$AppClientId="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # Paste your application (client) ID here.

$MsalParams = @{
   ClientId = $AppClientId
   TenantId = $TenantId
   Scopes   = 'https://graph.microsoft.com/User.Read.All','https://graph.microsoft.com/Files.ReadWrite','https://api.securitycenter.windows.com/AdvancedQuery.Read'
}

$MsalResponse = Get-MsalToken @MsalParams
$AccessToken  = $MsalResponse.AccessToken
 
$AccessToken # Display the token in PS console

Valider le jeton

  1. Copiez et collez le jeton dans JWT pour le décoder.
  2. Vérifiez que la revendication de rôles dans le jeton décodé contient les autorisations souhaitées.

Dans l’image suivante, vous pouvez voir un jeton décodé acquis à partir d’une application, avec Incidents.Read.Allles autorisations , Incidents.ReadWrite.Allet AdvancedHunting.Read.All :

Section Autorisations dans le volet Jeton décodé du portail Microsoft Defender

Utiliser le jeton pour accéder à l’API XDR Microsoft Defender

  1. Choisissez l’API que vous souhaitez utiliser (incidents ou repérage avancé). Pour plus d’informations, consultez API XDR Microsoft Defender prises en charge.
  2. Dans la requête HTTP que vous êtes sur le point d’envoyer, définissez l’en-tête d’autorisation sur "Bearer" <token>, le porteur étant le schéma d’autorisation et le jeton étant votre jeton validé.
  3. Le jeton expire dans l’heure. Vous pouvez envoyer plusieurs requêtes pendant ce temps avec le même jeton.

L’exemple suivant montre comment envoyer une demande pour obtenir une liste d’incidents à l’aide de C#.

    var httpClient = new HttpClient();
    var request = new HttpRequestMessage(HttpMethod.Get, "https://api.security.microsoft.com/api/incidents");

    request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

    var response = httpClient.SendAsync(request).GetAwaiter().GetResult();

Conseil

Voulez-vous en savoir plus ? Collaborez avec la communauté Microsoft Security dans notre communauté technique : Microsoft Defender XDR Tech Community.