MICROSOFT DEFENDER VOOR EINDPUNT-API's gebruiken

Van toepassing op:

• Plan 1 voor Microsoft Defender voor Eindpunt
• Plan 2 voor Microsoft Defender voor Eindpunt
• Microsoft Defender voor Bedrijven

Belangrijk

Geavanceerde opsporingsmogelijkheden zijn niet opgenomen in Defender voor Bedrijven.

Wilt u Microsoft Defender voor Eindpunt ervaren? Meld u aan voor een gratis proefversie.

Opmerking

Als u een klant van de Amerikaanse overheid bent, gebruikt u de URI's die worden vermeld in Microsoft Defender voor Eindpunt voor klanten van de Amerikaanse overheid.

Tip

Voor betere prestaties kunt u de server dichter bij uw geografische locatie gebruiken:

• api-us.securitycenter.microsoft.com
• api-eu.securitycenter.microsoft.com
• api-uk.securitycenter.microsoft.com
• api-au.securitycenter.microsoft.com

Op deze pagina wordt beschreven hoe u namens een gebruiker een toepassing maakt om programmatische toegang te krijgen tot Defender for Endpoint.

Als u programmatische toegang nodig hebt Microsoft Defender voor Eindpunt zonder een gebruiker, raadpleegt u Access Microsoft Defender voor Eindpunt met toepassingscontext.

Als u niet zeker weet welke toegang u nodig hebt, leest u de pagina Inleiding.

Microsoft Defender voor Eindpunt maakt veel van de gegevens en acties beschikbaar via een set programmatische API's. Met deze API's kunt u werkstromen automatiseren en innoveren op basis van Microsoft Defender voor Eindpunt mogelijkheden. Voor de API-toegang is OAuth2.0-verificatie vereist. Zie OAuth 2.0-autorisatiecodestroom voor meer informatie.

Over het algemeen moet u de volgende stappen uitvoeren om de API's te gebruiken:

• een Microsoft Entra-toepassing Creatie
• Een toegangstoken ophalen met behulp van deze toepassing
• Het token gebruiken voor toegang tot defender voor eindpunt-API

Op deze pagina wordt uitgelegd hoe u een Microsoft Entra-toepassing maakt, een toegangstoken opgeeft om te Microsoft Defender voor Eindpunt en het token valideert.

Opmerking

Bij het openen van Microsoft Defender voor Eindpunt API namens een gebruiker, hebt u de juiste toepassingsmachtiging en gebruikersmachtiging nodig. Als u niet bekend bent met gebruikersmachtigingen op Microsoft Defender voor Eindpunt, raadpleegt u Portaltoegang beheren met op rollen gebaseerd toegangsbeheer.

Tip

Als u gemachtigd bent om een actie uit te voeren in de portal, hebt u de machtiging om de actie uit te voeren in de API.

een app Creatie

1. Meld u aan bij Azure met een gebruikersaccount met de rol Globale beheerder .

2. Navigeer naar Microsoft Entra ID>App-registraties>Nieuwe registratie.

   

3. Wanneer de pagina Een toepassing registreren wordt weergegeven, voert u de registratiegegevens van uw toepassing in:

   • Naam : voer een betekenisvolle toepassingsnaam in die wordt weergegeven aan gebruikers van de app.

   • Ondersteunde accounttypen : selecteer welke accounts u wilt ondersteunen door uw toepassing.

     
     

     Ondersteunde accounttypen	Omschrijving
     Alleen accounts in deze organisatiemap	Selecteer deze optie als u een LOB-toepassing (Line-Of-Business) bouwt. Deze optie is niet beschikbaar als u de toepassing niet registreert in een map. Deze optie wordt toegewezen aan Microsoft Entra met één tenant. Dit is de standaardoptie, tenzij u de app buiten een map registreert. In gevallen waarin de app buiten een directory is geregistreerd, is de standaardinstelling Microsoft Entra multitenant- en persoonlijke Microsoft-accounts.
     Accounts in elke organisatiemap	Selecteer deze optie als u zich wilt richten op alle zakelijke en educatieve klanten. Deze optie wordt toegewezen aan een Microsoft Entra-only multitenant. Als u de app hebt geregistreerd als Microsoft Entra-only single-tenant, kunt u deze bijwerken naar Microsoft Entra multitenant en terug naar één tenant via de blade Verificatie.
     Accounts in elke organisatiemap en persoonlijke Microsoft-accounts	Selecteer deze optie om zich te richten op de breedste set klanten. Deze optie wordt toegewezen aan Microsoft Entra meerdere tenants en persoonlijke Microsoft-accounts. Als u de app hebt geregistreerd als Microsoft Entra multitenant- en persoonlijke Microsoft-accounts, kunt u dit niet wijzigen in de gebruikersinterface. In plaats daarvan moet u de manifesteditor van de toepassing gebruiken om de ondersteunde accounttypen te wijzigen.

   • Omleidings-URI (optioneel): selecteer het type app dat u bouwt, webclient of openbare client (mobiel & desktop) en voer vervolgens de omleidings-URI (of antwoord-URL) voor uw toepassing in.

     • Geef voor webtoepassingen de basis-URL van uw app op. Dit kan bijvoorbeeld http://localhost:31544 de URL zijn voor een web-app die wordt uitgevoerd op uw lokale computer. Gebruikers gebruiken deze URL om zich aan te melden bij een webclienttoepassing.

     • Geef voor openbare clienttoepassingen de URI op die door Microsoft Entra ID wordt gebruikt om tokenantwoorden te retourneren. Voer een waarde in die specifiek is voor uw toepassing, zoals myapp://auth.

     Bekijk onze quickstarts voor specifieke voorbeelden voor webtoepassingen of systeemeigen toepassingen.

     Wanneer u klaar bent, selecteert u Registreren.

4. Geef uw toepassing toegang tot Microsoft Defender voor Eindpunt en wijs de machtiging 'Waarschuwingen lezen' toe:

   • Selecteer op uw toepassingspagina API-machtigingenToevoegenmachtigings-API's >>die mijn organisatie gebruikt> het type WindowsDefenderATP en selecteer op WindowsDefenderATP.

     Opmerking

     WindowsDefenderATP wordt niet weergegeven in de oorspronkelijke lijst. Begin met het schrijven van de naam in het tekstvak om deze weer te geven.

     

   • Kies Gedelegeerde machtigingen>Waarschuwing.Lees> selecteer Machtigingen toevoegen.

     

   Belangrijk

   Selecteer de relevante machtigingen. Waarschuwingen lezen is slechts een voorbeeld.

   Bijvoorbeeld:

   • Als u geavanceerde query's wilt uitvoeren, selecteert u Machtiging geavanceerde query's uitvoeren .

   • Als u een apparaat wilt isoleren, selecteert u Machinemachtiging isoleren .

   • Als u wilt bepalen welke machtiging u nodig hebt, bekijkt u de sectie Machtigingen in de API die u wilt aanroepen.

   • Selecteer Toestemming verlenen.

     Opmerking

     Telkens wanneer u een machtiging toevoegt, moet u toestemming verlenen selecteren om de nieuwe machtiging van kracht te laten worden.

     

5. Noteer uw toepassings-id en uw tenant-id.

   Ga op de toepassingspagina naar Overzicht en kopieer de volgende informatie:

   

Een toegangstoken ophalen

Zie Microsoft Entra zelfstudie voor meer informatie over Microsoft Entra tokens.

C gebruiken#

• Kopieer/plak de onderstaande klasse in uw toepassing.

• Gebruik de methode AcquireUserTokenAsync met uw toepassings-id, tenant-id, gebruikersnaam en wachtwoord om een token te verkrijgen.

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

Het token valideren

Controleer of u een juist token hebt:

• Kopieer/plak in JWT het token dat u in de vorige stap hebt gekregen om het te decoderen.

• Valideer dat u een 'scp'-claim krijgt met de gewenste app-machtigingen.

• In de onderstaande schermopname ziet u een gedecodeerd token dat is verkregen uit de app in de zelfstudie:

  

Het token gebruiken om toegang te krijgen tot Microsoft Defender voor Eindpunt API

• Kies de API die u wilt gebruiken - Ondersteund Microsoft Defender voor Eindpunt API's.

• Stel de autorisatieheader in de HTTP-aanvraag die u verzendt in op Bearer {token}(Bearer is het autorisatieschema).

• De verlooptijd van het token is 1 uur (u kunt meer dan één aanvraag met hetzelfde token verzenden).

• Voorbeeld van het verzenden van een aanvraag om een lijst met waarschuwingen op te halen met behulp van 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
  

Zie ook

• Microsoft Defender voor Eindpunt-API's
• Toegang tot Microsoft Defender voor Eindpunt met toepassingscontext

Tip

Wil je meer weten? Engage met de Microsoft Security-community in onze Tech Community: Microsoft Defender voor Eindpunt Tech Community.