Utiliser les API Microsoft Defender pour point de terminaison

Article
06/25/2024

S’applique à :

Importante

Les fonctionnalités de repérage avancées ne sont pas incluses dans Defender pour les entreprises.

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 l’accès par programmation à Defender pour point de terminaison pour le compte d’un utilisateur.

Si vous avez besoin d’un accès par programmation à Microsoft Defender pour point de terminaison sans utilisateur, reportez-vous à Accéder à Microsoft Defender pour point de terminaison avec le contexte de l’application.

Si vous n’êtes pas sûr de l’accès dont vous avez besoin, lisez la page Introduction.

Microsoft Defender pour point de terminaison expose la plupart de ses données et actions par le biais d’un ensemble d’API programmatiques. Ces API vous permettent d’automatiser les flux de travail et d’innover en fonction des fonctionnalités de Microsoft 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éer une application Microsoft Entra
Obtenir un jeton d’accès à l’aide de cette application
Utiliser le jeton pour accéder à l’API Defender pour point de terminaison

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

Remarque

Lorsque vous accédez à l’API Microsoft Defender pour point de terminaison pour le compte d’un utilisateur, vous avez besoin de l’autorisation d’application et de l’autorisation utilisateur appropriées. Si vous n’êtes pas familiarisé avec les autorisations utilisateur sur Microsoft Defender pour point de terminaison, consultez Gérer l’accès au portail à l’aide du contrôle d’accès en fonction du rôle.

Conseil

Si vous avez l’autorisation d’effectuer une action dans le portail, vous avez l’autorisation d’effectuer l’action dans l’API.

Créer une application

Connectez-vous au Portail Azure.
Accédez à Microsoft Entra ID> Inscriptions >d’applicationsNouvelle inscription.

Lorsque la page Inscrire une application s’affiche, saisissez les informations d’inscription de votre application :

Nom : entrez un nom d’application explicite qui s’affiche pour les utilisateurs de l’application.

Types de compte pris en charge : sélectionnez les comptes à prendre en charge par l’application.

Types de comptes pris en charge	Description
Comptes dans cet annuaire organisationnel uniquement	Sélectionnez cette option si vous générez une application métier. Cette option n’est pas disponible si vous n’inscrivez pas l’application dans un répertoire. Cette option correspond à Microsoft Entra-only monolocataire. Cette option est l’option par défaut, sauf si vous inscrivez l’application en dehors d’un répertoire. Dans les cas où l’application est inscrite en dehors d’un répertoire, la valeur par défaut est Microsoft Entra multilocataire et comptes Microsoft personnels.
Comptes dans un annuaire organisationnel	Sélectionnez cette option si vous souhaitez cibler tous les clients professionnels et éducatifs. Cette option correspond à un multilocataire Microsoft Entra uniquement. Si vous avez inscrit l’application en tant que monolocataire Microsoft Entra uniquement, vous pouvez la mettre à jour pour qu’elle soit multilocataire Microsoft Entra et la revenir à un seul locataire via le panneau Authentification .
Comptes dans un annuaire organisationnel et comptes personnels Microsoft	Sélectionnez cette option pour cibler l’ensemble le plus large de clients. Cette option mappe aux comptes Microsoft Entra multilocataires et personnels Microsoft. Si vous avez inscrit l’application en tant que comptes Microsoft Microsoft Entra multilocataires et personnels, vous ne pouvez pas le modifier dans l’interface utilisateur. Vous devez utiliser l’éditeur de manifeste de l’application pour modifier les types de compte pris en charge.

URI de redirection (facultatif) : sélectionnez le type d’application que vous créez, Web ou Client public (mobile et bureau), puis entrez l’URI de redirection (ou URL de réponse).
- Pour les applications web, indiquez l’URL de base de votre application. Par exemple, http://localhost:31544 peut être l’URL d’une application web en cours d’exécution sur votre ordinateur local. Les utilisateurs peuvent utiliser cette URL pour se connecter à une application web cliente.
- Pour les applications clientes publiques, fournissez l’URI utilisé par l’ID Microsoft Entra pour retourner des réponses de jeton. Entrez une valeur spécifique de votre application, par exemple, myapp://auth.
Pour accéder à des exemples spécifiques aux applications web ou natives, consultez les Guides de démarrage rapides.

Lorsque vous avez terminé, sélectionnez Inscrire.

Autorisez votre application à accéder à Microsoft Defender pour point de terminaison et attribuez-lui l’autorisation « Lire les alertes » :
- Dans la page de votre application, sélectionnez Autorisations d’API> Ajouter des APId’autorisation>que mon organisation 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.
- Choisissez Autorisations> déléguéesAlerte.Lire>, sélectionnez Ajouter des autorisations.
Importante

Sélectionnez les autorisations appropriées. Les alertes de lecture n’en sont qu’un exemple.

Par exemple :
- Pour exécuter des requêtes avancées, sélectionnez l’autorisation Exécuter les requêtes avancées .
- Pour isoler un appareil, sélectionnez Isoler l’autorisation de l’ordinateur .
- 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.
Notez votre ID d’application et votre ID de locataire.

Dans la page de votre application, accédez à Vue d’ensemble et copiez les informations suivantes :

Obtenir un jeton d’accès

Pour plus d’informations sur les jetons Microsoft Entra, consultez tutoriel Microsoft Entra.

Utilisation de C#

Copiez/collez la classe ci-dessous dans votre application.

Utilisez la méthode AcquireUserTokenAsync avec votre ID d’application, id de locataire, nom d’utilisateur et mot de passe pour acquérir un jeton.

namespace WindowsDefenderATP
{
    using System.Net.Http;
    using System.Text;
    using System.Threading.Tasks;
    using Newtonsoft.Json.Linq;

    public static class WindowsDefenderATPUtils
    {
        private const string Authority = "https://login.microsoftonline.com";

        private const string WdatpResourceId = "https://api.securitycenter.microsoft.com";

        public static async Task<string> AcquireUserTokenAsync(string username, string password, string appId, string tenantId)
        {
            using (var httpClient = new HttpClient())
            {
                var urlEncodedBody = $"resource={WdatpResourceId}&client_id={appId}&grant_type=password&username={username}&password={password}";

                var stringContent = new StringContent(urlEncodedBody, Encoding.UTF8, "application/x-www-form-urlencoded");

                using (var response = await httpClient.PostAsync($"{Authority}/{tenantId}/oauth2/token", stringContent).ConfigureAwait(false))
                {
                    response.EnsureSuccessStatusCode();

                    var json = await response.Content.ReadAsStringAsync().ConfigureAwait(false);

                    var jObject = JObject.Parse(json);

                    return jObject["access_token"].Value<string>();
                }
            }
        }
    }
}

Valider le jeton

Vérifiez que vous avez un jeton correct :

Copiez/collez dans JWT le jeton que vous avez obtenu à l’étape précédente afin de le décoder.
Vérifiez que vous obtenez une revendication « scp » avec les autorisations d’application souhaitées.
Dans la capture d’écran ci-dessous, vous pouvez voir un jeton décodé acquis à partir de l’application dans le tutoriel :

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

Choisissez l’API que vous souhaitez utiliser : API Microsoft Defender pour point de terminaison prises en charge.
Définissez l’en-tête d’autorisation dans la requête HTTP que vous envoyez à « Porteur {token} » (le porteur est le schéma d’autorisation).
La durée d’expiration du jeton est de 1 heure (vous pouvez envoyer plusieurs requêtes avec le même jeton).

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 ? Collaborez avec la communauté Microsoft Security dans notre communauté technique : Microsoft Defender pour point de terminaison Tech Community.

Partager via

Utiliser les API Microsoft Defender pour point de terminaison

Créer une application

Obtenir un jeton d’accès

Utilisation de C#

Valider le jeton

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

Voir aussi

Commentaires

Ressources supplémentaires