Créer une application pour accéder aux API Microsoft 365 Defender au nom d’un utilisateurCreate an app to access Microsoft 365 Defender APIs on behalf of a user

Important

Le Centre de sécurité Microsoft 365 est à présent disponible.The improved Microsoft 365 security center is now available. Cette nouvelle expérience introduit Defender pour point de terminaison, Defender pour Office 365, Microsoft 365 Defender et bien plus encore dans le Centre de sécurité Microsoft 365.This new experience brings Defender for Endpoint, Defender for Office 365, Microsoft 365 Defender, and more into the Microsoft 365 security center. Découvrir les nouveautés.Learn what's new.

S’applique à :Applies to:

  • Microsoft 365 DefenderMicrosoft 365 Defender

Important

Certaines informations ont trait à un produit préalablement publié, qui peut être modifié de manière significative avant sa publication commerciale.Some information relates to prereleased product which may be substantially modified before it's commercially released. Microsoft n’offre aucune garantie, explicite ou implicite, concernant les informations fournies ici.Microsoft makes no warranties, express or implied, with respect to the information provided here.

Cette page explique comment créer une application pour obtenir un accès par programme à Microsoft 365 Defender pour le compte d’un seul utilisateur.This page describes how to create an application to get programmatic access to Microsoft 365 Defender on behalf of a single user.

Si vous avez besoin d’un accès par programmation à Microsoft 365 Defender sans utilisateur défini (par exemple, si vous écrivez une application en arrière-plan ou un daemon), voir Créer une application pour accéder à Microsoft 365 Defendersans utilisateur.If you need programmatic access to Microsoft 365 Defender without a defined user (for example, if you're writing a background app or daemon), see Create an app to access Microsoft 365 Defender without a user. Si vous devez fournir l’accès à plusieurs clients, par exemple, si vous fournissez des services à une grande organisation ou à un groupe de clients, voir Créer une application avec un accès partenaire aux API Microsoft 365 Defender. If you’re not sure which kind of access you need, see Get started.If you need to provide access for multiple tenants—for example, if you're serving a large organization or a group of customers—see Create an app with partner access to Microsoft 365 Defender APIs.If you're not sure which kind of access you need, see Get started.

Microsoft 365 Defender expose la plupart de ses données et actions par le biais d’un ensemble d’API de programmation.Microsoft 365 Defender exposes much of its data and actions through a set of programmatic APIs. Ces API vous aident à automatiser les flux de travail et à utiliser les fonctionnalités de Microsoft 365 Defender.Those APIs help you automate workflows and make use of Microsoft 365 Defender's capabilities. Cet accès à l’API nécessite une authentification OAuth2.0.This API access requires OAuth2.0 authentication. Pour plus d’informations, voir flux de code d’autorisation OAuth 2.0.For more information, see OAuth 2.0 Authorization Code Flow.

En règle générale, vous devez suivre les étapes suivantes pour utiliser ces API :In general, you'll need to take the following steps to use these APIs:

  • Créez une application Azure Active Directory (Azure AD).Create an Azure Active Directory (Azure AD) application.
  • Obtenez un jeton d’accès à l’aide de cette application.Get an access token using this application.
  • Utilisez le jeton pour accéder à l’API Microsoft 365 Defender.Use the token to access Microsoft 365 Defender API.

Cet article explique comment :This article explains how to:

  • Créer une application Azure ADCreate an Azure AD application
  • Obtenir un jeton d’accès à Microsoft 365 DefenderGet an access token to Microsoft 365 Defender
  • Valider le jetonValidate the token

Notes

Lorsque vous accédez à l’API Microsoft 365 Defender pour le compte d’un utilisateur, vous avez besoin des autorisations d’application et des autorisations utilisateur correctes.When accessing Microsoft 365 Defender API on behalf of a user, you will need the correct application permissions and user permissions.

Conseil

Si vous avez l’autorisation d’effectuer une action dans le portail, vous avez l’autorisation d’effectuer l’action dans l’API.If you have the permission to perform an action in the portal, you have the permission to perform the action in the API.

Créer une applicationCreate an app

  1. Connectez-vous à Azure en tant qu’utilisateur avec le rôle Administrateur général.Sign in to Azure as a user with the Global Administrator role.

  2. Accédez à Azure Active Directory App > registrations New > registration.Navigate to Azure Active Directory > App registrations > New registration.

    Image de Microsoft Azure et navigation vers l’inscription de l’application

  3. Dans le formulaire, choisissez un nom pour votre application et entrez les informations suivantes pour l’URI de redirection, puis sélectionnez Enregistrer.In the form, choose a name for your application and enter the following information for the redirect URI, then select Register.

    Image de la fenêtre Créer une application

  4. Dans la page de votre application, sélectionnez Autorisations API Ajouter des API d’autorisation que mon organisation utilise >, tapez Protection Microsoft contre les menaces, puis sélectionnez > > Protection Microsoft contre les menaces. On your application page, select API Permissions > Add permission > APIs my organization uses >, type Microsoft Threat Protection, and select Microsoft Threat Protection. Votre application peut désormais accéder à Microsoft 365 Defender.Your app can now access Microsoft 365 Defender.

    Conseil

    Microsoft Threat Protection est un ancien nom de Microsoft 365 Defender et n’apparaîtra pas dans la liste d’origine.Microsoft Threat Protection is a former name for Microsoft 365 Defender, and will not appear in the original list. Vous devez commencer à écrire son nom dans la zone de texte pour qu’il apparaisse.You need to start writing its name in the text box to see it appear.

    Image de la sélection des autorisations d’API

    • Choisissez Autorisations déléguées.Choose Delegated permissions. Choisissez les autorisations pertinentes pour votre scénario (par exemple Incident.Read), puis sélectionnez Ajouter des autorisations.Choose the relevant permissions for your scenario (for example Incident.Read), and then select Add permissions.

    Image de l’accès à l’API et de la sélection d’API

    Notes

    Vous devez sélectionner les autorisations pertinentes pour votre scénario.You need to select the relevant permissions for your scenario. Lire tous les incidents n’est qu’un exemple.Read all incidents is just an example. Pour déterminer l’autorisation qui vous est nécessaire, consultez la section Autorisations de l’API que vous voulez appeler.To determine which permission you need, please look at the Permissions section in the API you want to call.

    Par exemple, 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 l’ordinateur ».For instance, to run advanced queries, select the 'Run advanced queries' permission; to isolate a device, select the 'Isolate machine' permission.

  5. Sélectionnez Accorder le consentement de l’administrateur.Select Grant admin consent. Chaque fois que vous ajoutez une autorisation, vous devez sélectionner Accorder le consentement de l’administrateur pour qu’elle prenne effet.Every time you add a permission, you must select Grant admin consent for it to take effect.

    Image de l’octroi d’autorisations

  6. Enregistrez votre ID d’application et votre ID de client dans un endroit sûr.Record your application ID and your tenant ID somewhere safe. Ils sont répertoriés sous Vue d’ensemble sur la page de votre application.They're listed under Overview on your application page.

    Image de l’ID d’application créé

Obtenir un jeton d’accèsGet an access token

Pour plus d’informations sur les jetons Azure Active Directory, voir le didacticiel Azure AD.For more information on Azure Active Directory tokens, see the Azure AD tutorial.

Obtenir un jeton d’accès à l’aide de PowerShellGet an access token using PowerShell

if(!(Get-Package adal.ps)) { Install-Package -Name adal.ps } # Install the ADAL.PS package in case it's not already present

$tenantId = '' # Paste your directory (tenant) ID here.
$clientId = '' # Paste your application (client) ID here.
$redirectUri = '' # Paste your app's redirection URI

$authority = "https://login.windows.net/$tenantId"
$resourceUrl = 'https://api.security.microsoft.com'

$response = Get-ADALToken -Resource $resourceUrl -ClientId $cleintId -RedirectUri $redirectUri -Authority $authority -PromptBehavior:Always
$response.AccessToken | clip

$response.AccessToken

Valider le jetonValidate the token

  1. Copiez et collez le jeton dans JWT pour le décoder.Copy and paste the token into JWT to decode it.
  2. Assurez-vous que la revendication de rôles dans le jeton décodé contient les autorisations souhaitées.Make sure that the roles claim within the decoded token contains the desired permissions.

Dans l’image suivante, vous pouvez voir un jeton décodé acquis à partir d’une application, avec Incidents.Read.All Incidents.ReadWrite.All , et des AdvancedHunting.Read.All autorisations :In the following image, you can see a decoded token acquired from an app, with Incidents.Read.All, Incidents.ReadWrite.All, and AdvancedHunting.Read.All permissions:

Image de validation de jeton

Utiliser le jeton pour accéder à l’API Microsoft 365 DefenderUse the token to access the Microsoft 365 Defender API

  1. Choisissez l’API que vous souhaitez utiliser (incidents ou recherche avancée).Choose the API you want to use (incidents, or advanced hunting). Pour plus d’informations, voir API Microsoft 365 Defender pris en charge.For more information, see Supported Microsoft 365 Defender APIs.
  2. Dans la requête http que vous êtes sur le point d’envoyer, définissez l’en-tête d’autorisation sur , le porteur étant le schéma d’autorisation et le jeton comme jeton "Bearer" <token> validé. In the http request you're about to send, set the authorization header to "Bearer" <token>, Bearer being the authorization scheme, and token being your validated token.
  3. Le jeton expire dans un délai d’une heure.The token will expire within one hour. Vous pouvez envoyer plusieurs demandes pendant cette période avec le même jeton.You can send more than one request during this time with the same token.

L’exemple suivant montre comment envoyer une demande pour obtenir une liste d’incidents à l’aide de C#.The following example shows how to send a request to get a list of incidents using 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();