Créer une application pour accéder à Microsoft Defender XDR sans utilisateur

S’applique à :

• Microsoft Defender XDR

Cette page explique comment créer une application pour obtenir un accès par programmation à Microsoft Defender XDR sans utilisateur défini, par exemple, si vous créez un démon ou un service en arrière-plan.

Si vous avez besoin d’un accès par programmation à Microsoft Defender XDR pour le compte d’un ou de plusieurs utilisateurs, consultez Créer une application pour accéder à Microsoft Defender XDR API pour le compte d’un utilisateur et Créer une application avec un accès partenaire à Microsoft Defender XDR API. 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 via 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 à Microsoft Defender XDR’API.

Cet article explique comment :

• Créer une application Microsoft Entra
• Obtenir un jeton d’accès pour Microsoft Defender XDR
• Validez le jeton.

Créer une application

1. Connectez-vous à Azure.

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

   

3. Dans le formulaire, choisissez un nom pour votre application, puis sélectionnez Inscrire.

4. Dans la page de votre application, sélectionnez Api Autorisations> Ajouter des APId’autorisation>que mon organization 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 pour Microsoft Defender XDR et n’apparaît pas dans la liste d’origine. Vous devez commencer à écrire son nom dans la zone de texte pour le voir apparaître.

   

5. Sélectionnez Autorisations d’application. Choisissez les autorisations appropriées pour votre scénario (par exemple, Incident.Read.All), puis sélectionnez Ajouter des autorisations.

   

   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.

   Pour instance, 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 ».

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

   

7. Pour ajouter un secret à l’application, sélectionnez Certificats & secrets, ajoutez une description au secret, puis sélectionnez Ajouter.

   Conseil

   Après avoir sélectionné Ajouter, sélectionnez Copier la valeur du secret généré. Vous ne pourrez plus récupérer la valeur du secret après votre départ.

   

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

   

9. Pour Microsoft Defender XDR partenaires uniquement : suivez ces instructions pour l’accès aux partenaires via les API Microsoft Defender XDR, définissez votre application sur multilocataire afin qu’elle puisse être disponible dans tous les locataires une fois que vous recevez le consentement de l’administrateur. L’accès partenaire est requis pour les applications tierces, par exemple si vous créez une application destinée à s’exécuter dans les locataires de plusieurs clients. Il n’est pas nécessaire si vous créez un service que vous souhaitez exécuter uniquement dans votre locataire, par exemple une application pour votre propre utilisation qui interagira uniquement avec vos propres données. Pour définir votre application pour qu’elle soit multilocataire :

   • Accédez à Authentification et ajoutez https://portal.azure.com comme URI de redirection.

   • En bas de la page, sous Types de comptes pris en charge, sélectionnez le consentement Comptes dans n’importe quelle application d’annuaire d’organisation pour votre application multilocataire.

   Étant donné que votre application interagit avec Microsoft Defender XDR pour le compte de vos utilisateurs, elle doit être approuvée pour chaque locataire sur lequel vous envisagez de l’utiliser.

   L’administrateur Active Directory de chaque locataire doit sélectionner le lien de consentement et approuver votre application.

   Le lien de consentement a la structure suivante :

   https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=<00000000-0000-0000-0000-000000000000>&response_type=code&sso_reload=true
   

   Les chiffres 00000000-0000-0000-0000-000000000000 doivent être remplacés par votre ID d’application.

Terminé ! Vous avez correctement inscrit une application ! Consultez les exemples ci-dessous pour l’acquisition et la validation de jetons.

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 à l’aide de PowerShell

# This code gets the application context token and saves it to a file named "Latest-token.txt" under the current directory.

$tenantId = '' # Paste your directory (tenant) ID here
$clientId = '' # Paste your application (client) ID here
$appSecret = '' # Paste your own app secret here to test, then store it in a safe place, such as the Azure Key Vault!

$resourceAppIdUri = 'https://api.security.microsoft.com'
$oAuthUri = "https://login.windows.net/$tenantId/oauth2/token"

$authBody = [Ordered] @{
    resource = $resourceAppIdUri
    client_id = $clientId
    client_secret = $appSecret
    grant_type = 'client_credentials'
}

$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token

Out-File -FilePath "./Latest-token.txt" -InputObject $token

return $token

Obtenir un jeton d’accès à l’aide de C#

1. Créez une application console.

2. Installez NuGet Microsoft.Identity.Client.

3. Ajoutez la ligne suivante :

   using Microsoft.Identity.Client;
   

4. Copiez et collez le code suivant dans votre application (n’oubliez pas de mettre à jour les trois variables : tenantId, , clientId) appSecret:

   csharp
   string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here
   string appId = "11111111-1111-1111-1111-111111111111"; // Paste your own app ID here
   string appSecret = "22222222-2222-2222-2222-222222222222"; // Paste your own app secret here for a test, and then store it in a safe place! 
   const string authority = https://login.microsoftonline.com;
   const string audience = https://api.securitycenter.microsoft.com;
   
   IConfidentialClientApplication myApp = ConfidentialClientApplicationBuilder.Create(appId).WithClientSecret(appSecret).WithAuthority($"{authority}/{tenantId}").Build();
   
   List<string> scopes = new List<string>() { $"{audience}/.default" };
   
   AuthenticationResult authResult = myApp.AcquireTokenForClient(scopes).ExecuteAsync().GetAwaiter().GetResult();
   
   string token = authResult.AccessToken;
   

Obtenir un jeton d’accès à l’aide de Python

import json
import urllib.request
import urllib.parse

tenantId = '' # Paste your directory (tenant) ID here
clientId = '' # Paste your application (client) ID here
appSecret = '' # Paste your own app secret here to test, then store it in a safe place, such as the Azure Key Vault!

url = "https://login.windows.net/%s/oauth2/token" % (tenantId)

resourceAppIdUri = 'https://api.security.microsoft.com'

body = {
    'resource' : resourceAppIdUri,
    'client_id' : clientId,
    'client_secret' : appSecret,
    'grant_type' : 'client_credentials'
}

data = urllib.parse.urlencode(body).encode("utf-8")

req = urllib.request.Request(url, data)
response = urllib.request.urlopen(req)
jsonResponse = json.loads(response.read())
aadToken = jsonResponse["access_token"]

Obtenir un jeton d’accès à l’aide de curl

1. Ouvrez une invite de commandes et définissez CLIENT_ID sur votre ID d’application Azure.

2. Définissez CLIENT_SECRET à votre secret d’application Azure.

3. Définissez TENANT_ID sur l’ID de locataire Azure du client qui souhaite utiliser votre application pour accéder à Microsoft Defender XDR.

4. Exécutez la commande suivante :

   curl -i -X POST -H "Content-Type:application/x-www-form-urlencoded" -d "grant_type=client_credentials" -d "client_id=%CLIENT_ID%" -d "scope=https://api.security.microsoft.com/.default" -d "client_secret=%CLIENT_SECRET%" "https://login.microsoftonline.com/%TENANT_ID%/oauth2/v2.0/token" -k
   

   Une réponse réussie se présente comme suit :

   {"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn <truncated> aWReH7P0s0tjTBX8wGWqJUdDA"}
   

Valider le jeton

1. Copiez et collez le jeton dans le site web du validateur de jeton web JSON, 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 :

   

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

1. Choisissez l’API que vous souhaitez utiliser (incidents ou repérage avancé). Pour plus d’informations, consultez API Microsoft Defender XDR 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();

Articles connexes

• Vue d’ensemble des API Microsoft Defender XDR
• Accéder aux API Microsoft Defender XDR
• Créer une application « Hello monde »
• Créer une application pour accéder aux API Microsoft Defender XDR pour le compte d’un utilisateur
• Créer une application avec un accès partenaire multilocataire aux API Microsoft Defender XDR
• En savoir plus sur les limites et les licences des API
• Comprendre les codes d’erreur
• Gérer les secrets dans vos applications serveur avec Azure Key Vault
• Autorisation OAuth 2.0 pour la connexion utilisateur et l’accès à l’API