MICROSOFT DEFENDER VOOR EINDPUNT-API's gebruiken

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 maken
• 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.

Een app maken

1. Meld u aan bij Azure Portal.

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 voor gebruikers van de app.

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

     
     

     Ondersteunde accounttypen	Beschrijving
     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. Deze optie 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 multitenant. Als u de app hebt geregistreerd als Microsoft Entra-only single-tenant, kunt u deze bijwerken zodat deze wordt 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 multitenant 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-machtigingen>machtigings-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#

Dit voorbeeld gebruikt de Microsoft Authentication Library (MSAL) om een token interactief te verkrijgen. Voordat je het uitvoert:

• Voeg het Microsoft.Identity.Client NuGet-pakket toe aan uw project.
• Configureer bij je app-registratie een mobiel en desktopapplicatieplatform met de http://localhost redirect URI, zodat de interactieve flow het token kan teruggeven.
• Kopieer/plak de volgende klasse in je applicatie en roep vervolgens AcquireUserTokenAsync aan met je applicatie-ID en tenant-ID. De gebruiker wordt gevraagd om interactief in te loggen; Hun wachtwoord wordt nooit door jouw applicatie verwerkt.

    namespace WindowsDefenderATP
    {
        using System.Linq;
        using System.Threading.Tasks;
        using Microsoft.Identity.Client;

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

            // Microsoft Defender for Endpoint APIs expect tokens issued for this resource.
            private static readonly string[] Scopes = { "https://api.securitycenter.microsoft.com/.default" };

            public static async Task<string> AcquireUserTokenAsync(string appId, string tenantId)
            {
                // Public client application for a native (desktop) app.
                // No client secret or user password is stored or handled by the app.
                var app = PublicClientApplicationBuilder
                    .Create(appId)
                    .WithAuthority($"{Authority}/{tenantId}")
                    .WithDefaultRedirectUri() // http://localhost - register as a public client redirect URI
                    .Build();

                var account = (await app.GetAccountsAsync().ConfigureAwait(false)).FirstOrDefault();

                try
                {
                    // Reuse a cached token when one is available.
                    var silentResult = await app
                        .AcquireTokenSilent(Scopes, account)
                        .ExecuteAsync()
                        .ConfigureAwait(false);

                    return silentResult.AccessToken;
                }
                catch (MsalUiRequiredException)
                {
                    // First run or expired session: prompt the user to sign in.
                    // Uses the authorization code flow with PKCE and supports
                    // multifactor authentication and Conditional Access.
                    var interactiveResult = await app
                        .AcquireTokenInteractive(Scopes)
                        .ExecuteAsync()
                        .ConfigureAwait(false);

                    return interactiveResult.AccessToken;
                }
            }
        }
    }

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