Create une application pour accéder à Microsoft Defender XDR sans 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 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 Create une application pour accéder à Microsoft Defender XDR API pour le compte d’un utilisateur et Create une application disposant d’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 :

  • Create 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 :

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

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

    Onglet Nouvelle inscription dans le portail Microsoft Defender

  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.

    Onglet Utilisation des API du organization dans le portail Microsoft Defender

  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.

    Volet d’autorisation de l’application 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.

    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.

    Volet relatif à l’octroi de consentement dans le portail Microsoft Defender

  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.

    Volet Créer une application dans le portail Microsoft Defender

  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.

    Volet Vue d’ensemble dans le portail Microsoft Defender

  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 général 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.

Importante

Bien que les exemples de cette section vous encouragent à coller des valeurs secrètes à des fins de test, vous ne devez jamais coder en dur les secrets dans une application s’exécutant en production. Un tiers peut utiliser votre secret pour accéder aux ressources. Vous pouvez aider à sécuriser les secrets de votre application à l’aide d’Azure Key Vault. Pour obtenir un exemple pratique de la façon dont vous pouvez protéger votre application, consultez Gérer les secrets dans vos applications serveur avec Azure Key Vault.

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#

Remarque

Le code suivant a été testé avec Nuget Microsoft.Identity.Client 3.19.8.

Importante

Le package NuGet Microsoft.IdentityModel.Clients.ActiveDirectory et la bibliothèque Azure AD Authentication (ADAL) ont été déconseillés. Aucune nouvelle fonctionnalité n’a été ajoutée depuis le 30 juin 2020. Nous vous encourageons vivement à effectuer une mise à niveau. Pour plus d’informations, consultez le guide de migration .

  1. Create une nouvelle 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

Remarque

Curl est préinstallé sur Windows 10 versions 1803 et ultérieures. Pour les autres versions de Windows, téléchargez et installez l’outil directement à partir du site web officiel 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 :

    Volet Jeton décodé dans le portail Microsoft Defender

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();

Conseil

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