Créer une application pour accéder à Microsoft Defender pour point de terminaison sans utilisateur

Article
11/19/2024

S’applique à :

Importante

Les fonctionnalités de chasse avancées ne sont pas incluses dans Defender for Business.

Vous voulez découvrir Microsoft Defender pour point de terminaison ? Inscrivez-vous pour bénéficier d’un essai gratuit.

Remarque

Si vous êtes un client du gouvernement des États-Unis, utilisez les URI répertoriés dans Microsoft Defender pour point de terminaison pour les clients du gouvernement des États-Unis.

Conseil

Pour de meilleures performances, vous pouvez utiliser le serveur plus près de votre emplacement géographique :

us.api.security.microsoft.com
eu.api.security.microsoft.com
uk.api.security.microsoft.com
au.api.security.microsoft.com
swa.api.security.microsoft.com
ina.api.security.microsoft.com

Cette page explique comment créer une application pour obtenir un accès par programmation à Defender pour point de terminaison sans utilisateur. Si vous avez besoin d’un accès par programmation à Defender pour point de terminaison pour le compte d’un utilisateur, consultez Obtenir l’accès avec le contexte utilisateur. Si vous n’êtes pas certain de l’accès dont vous avez besoin, consultez Prise en main.

Microsoft Defender pour point de terminaison 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 de Defender pour point de terminaison. 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.
Obtenez un jeton d’accès à l’aide de cette application.
Utilisez le jeton pour accéder à l’API Defender pour point de terminaison.

Cet article explique comment créer une application Microsoft Entra, obtenir un jeton d’accès pour Microsoft Defender pour point de terminaison et valider le jeton.

Importante

Microsoft vous recommande d’utiliser des rôles disposant du moins d’autorisations. Cela contribue à renforcer la sécurité de votre organisation. Le rôle d’administrateur général dispose de privilèges élevés. Il doit être limité aux scénarios d’urgence lorsque vous ne pouvez pas utiliser un rôle existant.

Créer une application

Connectez-vous au Portail Azure.
Accédez à Microsoft Entra ID>inscriptions d'applications>Nouvelle inscription.
Dans le formulaire d’inscription, choisissez un nom pour votre application, puis sélectionnez Inscrire.
Pour permettre à votre application d’accéder à Defender pour point de terminaison et de lui attribuer l’autorisation « Lire toutes les alertes », dans la page de votre application, sélectionnez Api Autorisations>Ajouter des API d’autorisation>que mon organization utilise>, tapez WindowsDefenderATP, puis sélectionnez WindowsDefenderATP.

Remarque

WindowsDefenderATP n’apparaît pas dans la liste d’origine. Commencez à écrire son nom dans la zone de texte pour le voir apparaître.

Sélectionnez Autorisations >d’applicationAlert.Read.All, puis Ajouter des autorisations.
Sélectionnez les autorisations appropriées. Read All Alerts n’est qu’un exemple. Voici quelques exemples :
- Pour exécuter des requêtes avancées, sélectionnez l’autorisation Run advanced queries .
- Pour isoler un appareil, sélectionnez l’autorisation Isolate machine .
- Pour déterminer l’autorisation dont vous avez besoin, consultez la section Autorisations dans l’API que vous souhaitez appeler.
Sélectionnez Accorder le consentement.

Remarque

Chaque fois que vous ajoutez une autorisation, vous devez sélectionner Accorder le consentement pour que la nouvelle autorisation prenne effet.
Pour ajouter un secret à l’application, sélectionnez Certificats & secrets, ajoutez une description au secret, puis sélectionnez Ajouter.

Remarque

Après avoir sélectionné Ajouter, sélectionnez Copier la valeur du secret généré. Vous ne pourrez plus récupérer cette valeur après votre départ.
Notez votre ID d’application et votre ID de locataire. Dans la page de votre application, accédez à Vue d’ensemble et copiez ce qui suit.
Pour Microsoft Defender pour point de terminaison partenaires uniquement. Définissez votre application pour qu’elle soit mutualisée (disponible dans tous les locataires après le consentement). Cela est nécessaire pour les applications tierces (par exemple, si vous créez une application destinée à s’exécuter dans le locataire de plusieurs clients). Cela n’est pas obligatoire si vous créez un service que vous souhaitez exécuter uniquement dans votre locataire (par exemple, si vous créez une application pour votre propre utilisation qui interagira uniquement avec vos propres données). Pour définir votre application pour qu’elle soit mutualisée, procédez comme suit :
1. Accédez à Authentification et ajoutez https://portal.azure.com comme URI de redirection.
2. 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.
  
  Vous devez que votre application soit approuvée dans chaque locataire où vous envisagez de l’utiliser. Cela est dû au fait que votre application interagit avec Defender pour point de terminaison au nom de votre client.
  
  Vous (ou votre client si vous écrivez une application tierce) devez sélectionner le lien de consentement et approuver votre application. Le consentement doit être obtenu auprès d’un utilisateur disposant de privilèges d’administrateur dans Active Directory.
  
  Le lien de consentement est formé comme suit :
```
https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true
```
  Où 00000000-0000-0000-0000-000000000000 est remplacé 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.

Utiliser PowerShell

# This script acquires the App Context Token and stores it in the variable $token for later use in the script.
# Paste your Tenant ID, App ID, and App Secret (App key) into the indicated quotes below.

$tenantId = '' ### Paste your tenant ID here
$appId = '' ### Paste your Application ID here
$appSecret = '' ### Paste your Application key here

$sourceAppIdUri = 'https://api.securitycenter.microsoft.com/.default'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/v2.0/token"
$authBody = [Ordered] @{
    scope = "$sourceAppIdUri"
    client_id = "$appId"
    client_secret = "$appSecret"
    grant_type = 'client_credentials'
}
$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token
$token

Utiliser C# :

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 .

Créez une application console.
Installez NuGet Microsoft.Identity.Client.
Ajoutez les éléments suivants :
```
using Microsoft.Identity.Client;
```

Copiez et collez le code suivant dans votre application (n’oubliez pas de mettre à jour les trois variables : ) : tenantId, appId, 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;

Utiliser Python

Consultez Obtenir un jeton à l’aide de Python.

Utiliser Curl

Remarque

La procédure suivante suppose que Curl pour Windows est déjà installé sur votre ordinateur.

Ouvrez une invite de commandes et définissez CLIENT_ID sur votre ID d’application Azure.
Définissez sur CLIENT_SECRET votre secret d’application Azure.
Définissez TENANT_ID sur l’ID de locataire Azure du client qui souhaite utiliser votre application pour accéder à Defender pour point de terminaison.

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

Vous obtenez une réponse qui ressemble à l’extrait de code suivant :

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

Valider le jeton

Vérifiez que vous avez le jeton correct :

Copiez et collez le jeton que vous avez obtenu à l’étape précédente dans JWT afin de le décoder.
Vérifiez que vous obtenez une revendication de rôles avec les autorisations souhaitées.

Dans l’image suivante, vous pouvez voir un jeton décodé acquis à partir d’une application avec des autorisations pour tous les rôles de Microsoft Defender pour point de terminaison :

Utiliser le jeton pour accéder à Microsoft Defender pour point de terminaison’API

Choisissez l’API que vous souhaitez utiliser. Pour plus d’informations, consultez API Defender pour point de terminaison prises en charge.
Définissez l’en-tête d’autorisation dans la http requête à Bearer {token} laquelle vous envoyez (le porteur est le schéma d’autorisation).
La durée d’expiration du jeton est d’une heure. Vous pouvez envoyer plusieurs requêtes avec le même jeton.

Voici un exemple d’envoi d’une demande pour obtenir une liste d’alertes à l’aide de C# :

var httpClient = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Get, "https://api.securitycenter.microsoft.com/api/alerts");

request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

var response = httpClient.SendAsync(request).GetAwaiter().GetResult();

// Do something useful with the response

Voir aussi

Conseil

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

Partager via

Créer une application pour accéder à Microsoft Defender pour point de terminaison sans utilisateur

Créer une application

Obtenir un jeton d’accès

Utiliser PowerShell

Utiliser C# :

Utiliser Python

Utiliser Curl

Valider le jeton

Utiliser le jeton pour accéder à Microsoft Defender pour point de terminaison’API

Voir aussi

Commentaires

Ressources supplémentaires