Créer une application avec un accès partenaire aux API Microsoft Defender XDR

Créez une application Microsoft Entra qui dispose d’un accès programmatique à Microsoft Defender pour le compte des utilisateurs dans plusieurs locataires. Les applications multilocataires sont utiles pour servir de grands groupes d’utilisateurs.

Si vous avez besoin d’un accès programmatique à Microsoft Defender pour le compte d’un seul utilisateur, consultez Créer une application pour accéder à Microsoft Defender API pour le compte d’un utilisateur. Si vous avez besoin d'un accès sans utilisateur explicitement défini (par exemple, si vous écrivez une application ou un démon en arrière-plan), consultez Créer une application pour accéder à Microsoft Defender sans utilisateur. Si vous ne savez pas quel type d’accès vous avez besoin, consultez Prise en main.

Microsoft Defender expose une grande partie de ses données et actions par le biais d’un ensemble d’API programmatiques. Ces API vous aident à automatiser les flux de travail et à utiliser les fonctionnalités de Microsoft Defender. 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 Microsoft Defender.

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

• Créer une application Microsoft Entra multilocataire
• Obtenez le consentement de l’administrateur pour que votre application accède aux ressources Microsoft Defender dont elle a besoin.
• Obtenir un jeton d’accès pour Microsoft Defender
• Valider le jeton

Microsoft Defender expose une grande partie de ses données et actions par le biais d’un ensemble d’API programmatiques. Ces API vous aident à automatiser les flux de travail et à innover en fonction des fonctionnalités de Microsoft Defender. 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 :

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

Les étapes suivantes vous guident tout au long de la création d’une application Microsoft Entra multilocataire, de l’obtention d’un jeton d’accès pour Microsoft Defender et de la validation du jeton.

Créer l’application multilocataire

1. Connectez-vous à Azure.

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

   

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.

   

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

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

   Un administrateur 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 en tant qu’administrateur du locataire de l’utilisateur et accordez le consentement pour 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.

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#

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:

   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 sur 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.
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 :

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

Articles connexes

• Vue d’ensemble des API Microsoft Defender
• Accéder aux API Microsoft Defender
• Créer une application « Hello world »
• Créer une application pour accéder à Microsoft Defender XDR sans utilisateur
• Créer une application pour accéder aux API Microsoft Defender XDR 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