Create une application avec un accès partenaire aux API Microsoft Defender XDR

  • 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 Microsoft Entra qui dispose d’un accès programmatique à Microsoft Defender XDR, pour le compte d’utilisateurs sur plusieurs locataires. Les applications multilocataires sont utiles pour servir de grands groupes d’utilisateurs.

Si vous avez besoin d’un accès par programmation à Microsoft Defender XDR pour le compte d’un seul utilisateur, consultez Create une application pour accéder à Microsoft Defender XDR API pour le compte d’un utilisateur. Si vous avez besoin d’un accès sans définition explicite d’un utilisateur (par exemple, si vous écrivez une application en arrière-plan ou un démon), consultez Create une application pour accéder à Microsoft Defender XDR sans utilisateur. 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.

Étant donné que cette application est multilocataire, vous aurez également besoin du consentement administrateur de chaque locataire pour le compte de ses utilisateurs.

Cet article explique comment :

  • Create une application de Microsoft Entra multilocataire
  • Obtenez le consentement autorisé de votre administrateur utilisateur pour que votre application accède aux Microsoft Defender XDR dont elle a besoin.
  • Obtenir un jeton d’accès pour Microsoft Defender XDR
  • Valider le jeton

Microsoft Defender XDR expose la plupart de ses données et actions via un ensemble d’API programmatiques. Ces API vous aideront à automatiser les flux de travail et à innover en fonction des fonctionnalités Microsoft Defender XDR. 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 :

  • Create une application Microsoft Entra multilocataire.
  • Obtenez l’autorisation (consentement) de votre administrateur utilisateur pour que votre application accède aux ressources Microsoft Defender XDR dont elle a besoin.
  • Obtenez un jeton d’accès à l’aide de cette application.
  • Utilisez le jeton pour accéder à Microsoft Defender XDR’API.

Les étapes suivantes expliquent comment créer une application Microsoft Entra multilocataire, obtenir un jeton d’accès pour Microsoft Defender XDR et valider le jeton.

Create l’application multilocataire

  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.

    Section d’inscription d’une application dans le portail Microsoft Defender

  3. Dans le formulaire d’inscription :

    • Choisissez un nom pour votre application.
    • Dans Types de comptes pris en charge, sélectionnez Comptes dans n’importe quel annuaire organisationnel (n’importe quel annuaire Microsoft Entra) - Multilocataire.
    • Renseignez la section URI de redirection . Sélectionnez Type Web et donnez à l’URI de redirection .https://portal.azure.com

    Une fois que vous avez terminé de remplir le formulaire, sélectionnez Inscrire.

    Sections d’inscription d’une application dans le portail Microsoft Defender

  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.

    Section Utilisation des API 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 d’une 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.

    Section pour accorder le consentement de l’administrateur 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.

    Section Ajout de secret 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. Ajoutez l’application au locataire de votre utilisateur.

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

    Un administrateur général du locataire de votre utilisateur doit afficher le lien de consentement et approuver votre application.

    Le lien de consentement se présente sous la forme 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.

    Après avoir cliqué sur le lien de consentement, connectez-vous avec l’administrateur général du locataire de l’utilisateur et donnez votre consentement à l’application.

    Page de l’application de consentement dans le portail Microsoft Defender

    Vous devez également demander à votre utilisateur son ID de locataire. L’ID de locataire est l’un des identificateurs utilisés pour acquérir des jetons d’accès.

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

Conseil

Dans les exemples suivants, utilisez l’ID de locataire d’un utilisateur pour tester que le script fonctionne.

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!

$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:

    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 de l’utilisateur 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://securitycenter.onmicrosoft.com/windowsatpservice/.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.