Microsoft Defender voor Eindpunt-API's gebruiken

Artikel
06/24/2024

Van toepassing op:

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:

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

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 tot Microsoft Defender voor Eindpunt zonder een gebruiker, raadpleegt u Toegang tot 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 de mogelijkheden van Microsoft Defender for Endpoint. 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 voor Microsoft Defender voor Eindpunt en het token valideert.

Opmerking

Wanneer u namens een gebruiker toegang krijgt tot de Microsoft Defender for Endpoint-API, hebt u de juiste toepassingsmachtiging en gebruikersmachtiging nodig. Als u niet bekend bent met gebruikersmachtigingen voor 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 maken

Meld u aan bij Azure Portal.
Navigeer naar Microsoft Entra ID>App-registraties>Nieuwe registratie.

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-only single-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-only multitenant. Als u de app hebt geregistreerd als Microsoft Entra-only single-tenant, kunt u deze bijwerken naar Microsoft Entra-multitenant en teruggaan 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.

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.
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 voor toegang tot de Microsoft Defender for Endpoint-API

Kies de API die u wilt gebruiken- Ondersteunde 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

Tip

Wil je meer weten? Neem contact op met de Microsoft Security-community in onze Tech Community: Microsoft Defender for Endpoint Tech Community.

Delen via