Create une application avec un accès partenaire aux API Microsoft Defender XDR
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
Connectez-vous à Azure en tant qu’utilisateur avec le rôle Administrateur général .
Accédez à Microsoft Entra ID>inscriptions d'applications>Nouvelle inscription.
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.
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.
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 ».
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.
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.
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.
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.
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 .
Create une nouvelle application console.
Installez NuGet Microsoft.Identity.Client.
Ajoutez la ligne suivante :
using Microsoft.Identity.Client;
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.
- Ouvrez une invite de commandes et définissez CLIENT_ID sur votre ID d’application Azure.
- Définissez CLIENT_SECRET à votre secret d’application Azure.
- Définissez TENANT_ID sur l’ID de locataire Azure de l’utilisateur qui souhaite utiliser votre application pour accéder à Microsoft Defender XDR.
- 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
- Copiez et collez le jeton dans le site web du validateur de jeton web JSON, JWT, pour le décoder.
- 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.All
les autorisations , Incidents.ReadWrite.All
et AdvancedHunting.Read.All
:
Utiliser le jeton pour accéder à l’API Microsoft Defender XDR
- Choisissez l’API que vous souhaitez utiliser (incidents ou repérage avancé). Pour plus d’informations, consultez API Microsoft Defender XDR prises en charge.
- 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é. - 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
- Create une application « Hello monde »
- Create une application pour accéder à Microsoft Defender XDR sans utilisateur
- Create une application pour accéder à Microsoft Defender XDR API pour le compte d’un utilisateur
- 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
Conseil
Voulez-vous en savoir plus ? Engage avec la communauté Microsoft Security dans notre communauté technique : Microsoft Defender XDR Tech Community.