Créer une application avec un accès partenaire aux API Microsoft 365 DefenderCreate an app with partner access to Microsoft 365 Defender APIs

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 Azure Active Directory qui dispose d’un accès par programmation à Microsoft 365 Defender, pour le compte d’utilisateurs sur plusieurs clients.This page describes how to create an Azure Active Directory app that has programmatic access to Microsoft 365 Defender, on behalf of users across multiple tenants. Les applications multi-clients sont utiles pour servir de grands groupes d’utilisateurs.Multi-tenant apps are useful for serving large groups of users.

Si vous avez besoin d’un accès par programme à Microsoft 365 Defender pour le compte d’un seul utilisateur, voir Créer une application pour accéder aux API Microsoft 365 Defenderau nom d’un utilisateur.If you need programmatic access to Microsoft 365 Defender on behalf of a single user, see Create an app to access Microsoft 365 Defender APIs on behalf of a user. Si vous avez besoin d’un accès sans utilisateur explicitement 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 access without a user explicitly defined (for example, if you're writing a background app or daemon), see Create an app to access Microsoft 365 Defender without a user. If you’re not sure which kind of access you need, see Get started.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.

Étant donné que cette application est multi-locataire, vous aurez également besoin du consentement de l’administrateur de chaque client pour le compte de ses utilisateurs. Since this app is multi-tenant, you'll also need admin consent from each tenant on behalf of its users.

Cet article explique comment :This article explains how to:

  • Créer une application Azure AD multi-clientCreate a multi-tenant Azure AD application
  • Obtenez l’autorisation de votre administrateur utilisateur pour que votre application accède à Microsoft 365 Defender avec les ressources dont elle a besoin.Get authorized consent from your user administrator for your application to access the Microsoft 365 Defender that resources it needs.
  • Obtenir un jeton d’accès à Microsoft 365 DefenderGet an access token to Microsoft 365 Defender
  • Valider le jetonValidate the token

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 aideront à automatiser les flux de travail et à faire preuve d’innovation en fonction des fonctionnalités de Microsoft 365 Defender.Those APIs will help you automate work flows and innovate based on Microsoft 365 Defender capabilities. L’accès à l’API nécessite une authentification OAuth2.0.The 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 les API :In general, you’ll need to take the following steps to use the APIs:

  • Créez une application Azure AD à plusieurs locataires.Create a multi-tenant Azure AD application.
  • Obtenez l’autorisation (consentement) de votre administrateur utilisateur pour que votre application accède aux ressources Microsoft 365 Defender dont elle a besoin.Get authorized (consent) by your user administrator for your application to access Microsoft 365 Defender resources it needs.
  • 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.

Les étapes suivantes vous guident dans la création d’une application Azure AD à plusieurs clients, l’utilisation d’un jeton d’accès à Microsoft 365 Defender et la validation du jeton.The following steps with guide you how to create a multi-tenant Azure AD application, get an access token to Microsoft 365 Defender and validate the token.

Créer l’application multi-clientCreate the multi-tenant 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 d’inscription :In the registration form:

    • Choisissez un nom pour votre application.Choose a name for your application.
    • À partir des types de comptes pris en charge, sélectionnez Comptes dans n’importe quel annuaire d’organisation (n’importe quel annuaire Azure AD) - Multi-client.From Supported account types, select Accounts in any organizational directory (Any Azure AD directory) - Multitenant.
    • Remplissez la section URI de redirection.Fill out the Redirect URI section. Sélectionnez type Web et donnez l’URI de redirection en https://portal.azure.com tant que .Select type Web and give the redirect URI as https://portal.azure.com.

    Une fois que vous avez terminé de remplir le formulaire, sélectionnez Enregistrer.After you're done filling out the form, select Register.

    Image du formulaire Inscrire 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

  5. Sélectionnez les autorisations d’application.Select Application permissions. Choisissez les autorisations pertinentes pour votre scénario (par exemple, Incident.Read.All), puis sélectionnez Ajouter des autorisations.Choose the relevant permissions for your scenario (for example, Incident.Read.All), 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.

  6. 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

  7. Pour ajouter une secret à l’application, sélectionnez Certificats & secrets, ajoutez une description à la secret, puis sélectionnez Ajouter.To add a secret to the application, select Certificates & secrets, add a description to the secret, then select Add.

    Conseil

    Après avoir sélectionné Ajouter, sélectionnez copier la valeur de secret générée.After you select Add, select copy the generated secret value. Vous ne pourrez pas récupérer la valeur secrète après votre départ.You won't be able to retrieve the secret value after you leave.

    Image de la clé de création d’application

  8. 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éé

  9. Ajoutez l’application au client de votre utilisateur.Add the application to your user's tenant.

    Étant donné que votre application interagit avec Microsoft 365 Defender pour le compte de vos utilisateurs, elle doit être approuvée pour chaque client sur lequel vous avez l’intention de l’utiliser.Since your application interacts with Microsoft 365 Defender on behalf of your users, it needs be approved for every tenant on which you intend to use it.

    Un administrateur général du client de votre utilisateur doit afficher le lien de consentement et approuver votre application.A Global Administrator from your user's tenant needs to view the consent link and approve your application.

    Le lien de consentement est de la forme :Consent link is of the form:

    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.The digits 00000000-0000-0000-0000-000000000000 should be replaced with your Application ID.

    Après avoir cliqué sur le lien de consentement, connectez-vous avec l’administrateur général du client de l’utilisateur et consentez à l’application.After clicking on the consent link, sign in with the Global Administrator of the user's tenant and consent the application.

    Image de consentement

    Vous devez également demander à votre utilisateur son ID de client.You'll also need to ask your user for their tenant ID. L’ID de client est l’un des identificateurs utilisés pour acquérir des jetons d’accès.The tenant ID is one of the identifiers used to acquire access tokens.

  • Terminé !Done! Vous avez réussi à inscrire une application !You've successfully registered an application!
  • Voir les exemples ci-dessous pour l’acquisition et la validation des jetons.See examples below for token acquisition and validation.

Obtenir un jeton d’accèsGet an access token

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

Important

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 des secrets dans une application en cours d’exécution en production.Although the examples in this section encourage you to paste in secret values for testing purposes, you should never hardcode secrets into an application running in production. Un tiers peut utiliser votre secret pour accéder aux ressources.A third party could use your secret to access resources. Vous pouvez aider à sécuriser les secrets de votre application à l’aide d’Azure Key Vault.You can help keep your app's secrets secure by using Azure Key Vault. Pour obtenir un exemple pratique de la façon dont vous pouvez protéger votre application, voir Gérer les secrets dans vos applications serveur avec Azure Key Vault.For a practical example of how you can protect your app, see Manage secrets in your server apps with Azure Key Vault.

Conseil

Dans les exemples suivants, utilisez l’ID de locataire d’un utilisateur pour tester le fonctionnement du script.In the following examples, use a user's tenant ID to test that the script is working.

Obtenir un jeton d’accès à l’aide de PowerShellGet an access token using 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#Get an access token using C#

Notes

Le code suivant a été testé avec Nuget Microsoft.IdentityModel.Clients.ActiveDirectory 3.19.8.The following code was tested with Nuget Microsoft.IdentityModel.Clients.ActiveDirectory 3.19.8.

  1. Créez une application console.Create a new console application.

  2. Installez NuGet Microsoft.IdentityModel.Clients.ActiveDirectory.Install NuGet Microsoft.IdentityModel.Clients.ActiveDirectory.

  3. Ajoutez la ligne suivante :Add the following line:

    using Microsoft.IdentityModel.Clients.ActiveDirectory;
    
  4. Copiez et collez le code suivant dans votre application (n’oubliez pas de mettre à jour les trois variables tenantId : , , ) clientId appSecret :Copy and paste the following code into your app (don't forget to update the three variables: tenantId, clientId, appSecret):

    string tenantId = ""; // Paste your directory (tenant) ID here
    string clientId = ""; // Paste your application (client) ID here
    string appSecret = ""; // Paste your own app secret here to test, then store it in a safe place, such as the Azure Key Vault!
    
    const string authority = "https://login.windows.net";
    const string wdatpResourceId = "https://api.security.microsoft.com";
    
    AuthenticationContext auth = new AuthenticationContext($"{authority}/{tenantId}/");
    ClientCredential clientCredential = new ClientCredential(clientId, appSecret);
    AuthenticationResult authenticationResult = auth.AcquireTokenAsync(wdatpResourceId, clientCredential).GetAwaiter().GetResult();
    string token = authenticationResult.AccessToken;
    

Obtenir un jeton d’accès à l’aide de PythonGet an access token using 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.securitycenter.windows.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 l’outilGet an access token using curl

Notes

Il est préinstallé sur Windows 10, versions 1803 et ultérieures.Curl is pre-installed on Windows 10, versions 1803 and later. Pour les autres versions de Windows, téléchargez et installez l’outil directement à partir du site web officiel de lancement.For other versions of Windows, download and install the tool directly from the official curl website.

  1. Ouvrez une invite de commandes et définissez CLIENT_ID sur votre ID d’application Azure.Open a command prompt, and set CLIENT_ID to your Azure application ID.
  2. Définissez CLIENT_SECRET sur votre secret d’application Azure.Set CLIENT_SECRET to your Azure application secret.
  3. Définissez TENANT_ID sur l’ID de locataire Azure de l’utilisateur qui souhaite utiliser votre application pour accéder à Microsoft 365 Defender.Set TENANT_ID to the Azure tenant ID of the user that wants to use your app to access Microsoft 365 Defender.
  4. Exécutez la commande suivante :Run the following command:
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 ressemblera à ceci :A successful response will look like this:

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

Valider le jetonValidate the token

  1. Copiez et collez le jeton dans le site web de validation de jeton web JSON, JWT, pour le décoder.Copy and paste the token into the JSON web token validator website, 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();