Een app maken voor toegang tot Microsoft Defender voor Eindpunt zonder een gebruiker

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:

• 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
• ina.api.security.microsoft.com

Op deze pagina wordt beschreven hoe u een toepassing maakt om programmatische toegang te krijgen tot Defender voor Eindpunt zonder een gebruiker. Zie Toegang krijgen met gebruikerscontext als u namens een gebruiker programmatische toegang tot Defender voor Eindpunt nodig hebt. Als u niet zeker weet welke toegang u nodig hebt, raadpleegt u Aan de slag.

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 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.
• Haal een toegangstoken op met behulp van deze toepassing.
• Gebruik het token voor toegang tot de Defender for Endpoint-API.

In dit artikel wordt uitgelegd hoe u een Microsoft Entra-toepassing maakt, een toegangstoken voor Microsoft Defender voor Eindpunt opkrijgt en het token valideert.

Belangrijk

Microsoft raadt u aan rollen te gebruiken met de minste machtigingen. Dit helpt bij het verbeteren van de beveiliging voor uw organisatie. Globale beheerder is een zeer bevoorrechte rol die moet worden beperkt tot scenario's voor noodgevallen wanneer u een bestaande rol niet kunt gebruiken.

Een app maken

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

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

   

3. Kies in het registratieformulier een naam voor uw toepassing en selecteer vervolgens Registreren.

4. Als u wilt dat uw app toegang krijgt tot Defender voor Eindpunt en de machtiging Alle waarschuwingen lezen wilt toewijzen, selecteert u API-machtigingenToevoegenmachtigings-API's >> diemijn organisatie gebruikt>, typt u WindowsDefenderATP en selecteert u vervolgens 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.

   

   Selecteer Toepassingsmachtigingen>Waarschuwing.Read.All en selecteer vervolgens Machtigingen toevoegen.

   

5. Selecteer de juiste machtigingen. Read All Alerts is slechts een voorbeeld. Dit zijn enkele voorbeelden:

   • Als u geavanceerde query's wilt uitvoeren, selecteert u de Run advanced queries machtiging.
   • Als u een apparaat wilt isoleren, selecteert u de Isolate machine machtiging.
   • Als u wilt bepalen welke machtiging u nodig hebt, bekijkt u de sectie Machtigingen in de API die u wilt aanroepen.

6. Selecteer Toestemming verlenen.

   Opmerking

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

   

7. Als u een geheim wilt toevoegen aan de toepassing, selecteert u Certificaten & geheimen, voegt u een beschrijving toe aan het geheim en selecteert u vervolgens Toevoegen.

   Opmerking

   Nadat u Toevoegen hebt geselecteerd, selecteert u de gegenereerde geheime waarde kopiëren. U kunt deze waarde niet meer ophalen nadat u deze hebt verlaten.

   

8. Noteer uw toepassings-id en uw tenant-id. Ga op de toepassingspagina naar Overzicht en kopieer het volgende.

   

9. Alleen voor Microsoft Defender voor Eindpunt-partners. Stel uw app in op multitenant (beschikbaar in alle tenants na toestemming). Dit is vereist voor apps van derden (bijvoorbeeld als u een app maakt die is bedoeld om te worden uitgevoerd in de tenant van meerdere klanten). Dit is niet vereist als u een service maakt die u alleen in uw tenant wilt uitvoeren (bijvoorbeeld als u een toepassing maakt voor uw eigen gebruik die alleen met uw eigen gegevens communiceert). Als u wilt instellen dat uw app meerdere tenants heeft, voert u de volgende stappen uit:

   1. Ga naar Verificatie en voeg toe https://portal.azure.com als omleidings-URI.

   2. Selecteer onder aan de pagina onder Ondersteunde accounttypen de toestemming voor accounts in een organisatiemaptoepassing voor uw app met meerdere tenants.

      U moet uw toepassing goedkeuren in elke tenant waar u deze wilt gebruiken. Dit komt doordat uw toepassing namens uw klant communiceert met Defender voor Eindpunt.

      U (of uw klant als u een app van derden schrijft) moet de toestemmingskoppeling selecteren en uw app goedkeuren. De toestemming moet worden uitgevoerd met een gebruiker met beheerdersbevoegdheden in Active Directory.

      De toestemmingskoppeling wordt als volgt gevormd:

      https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true
      

      Waarbij 00000000-0000-0000-0000-000000000000 wordt vervangen door uw toepassings-id.

Gereed! U hebt een aanvraag geregistreerd! Bekijk hieronder voorbeelden voor het verkrijgen en valideren van tokens.

Een toegangstoken ophalen

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

PowerShell gebruiken

# This script acquires the App Context Token and stores it in the variable $token for later use in the script.
# Paste your Tenant ID, App ID, and App Secret (App key) into the indicated quotes below.

$tenantId = '' ### Paste your tenant ID here
$appId = '' ### Paste your Application ID here
$appSecret = '' ### Paste your Application key here

$sourceAppIdUri = 'https://api.securitycenter.microsoft.com/.default'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/v2.0/token"
$authBody = [Ordered] @{
    scope = "$sourceAppIdUri"
    client_id = "$appId"
    client_secret = "$appSecret"
    grant_type = 'client_credentials'
}
$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token
$token

Gebruik C#:

De volgende code is getest met NuGet Microsoft.Identity.Client 3.19.8.

Belangrijk

Het NuGet-pakket Microsoft.IdentityModel.Clients.ActiveDirectory en Azure AD Authentication Library (ADAL) zijn afgeschaft. Er zijn sinds 30 juni 2020 geen nieuwe functies toegevoegd. We raden u ten zeere aan om een upgrade uit te voeren. Raadpleeg de migratiehandleiding voor meer informatie.

1. Maak een nieuwe consoletoepassing.

2. Installeer NuGet Microsoft.Identity.Client.

3. Voeg het volgende toe:

   using Microsoft.Identity.Client;
   

4. Kopieer en plak de volgende code in uw app (vergeet niet de drie variabelen bij te werken: tenantId, appId, appSecret):

   string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here
   string appId = "11111111-1111-1111-1111-111111111111"; // Paste your own app ID here
   string appSecret = "22222222-2222-2222-2222-222222222222"; // Paste your own app secret here for a test, and then store it in a safe place! 
   const string authority = "https://login.microsoftonline.com";
   const string audience = "https://api.securitycenter.microsoft.com";
   
   IConfidentialClientApplication myApp = ConfidentialClientApplicationBuilder.Create(appId).WithClientSecret(appSecret).WithAuthority($"{authority}/{tenantId}").Build();
   
   List<string> scopes = new List<string>() { $"{audience}/.default" };
   
   AuthenticationResult authResult = myApp.AcquireTokenForClient(scopes).ExecuteAsync().GetAwaiter().GetResult();
   
   string token = authResult.AccessToken;
   

Python gebruiken

Zie Token ophalen met Python.

Curl gebruiken

Opmerking

In de volgende procedure wordt ervan uitgegaan dat Curl voor Windows al op uw computer is geïnstalleerd.

1. Open een opdrachtprompt en stel in CLIENT_ID op uw Azure-toepassings-id.

2. Stel in CLIENT_SECRET op uw Azure-toepassingsgeheim.

3. Stel in TENANT_ID op de Azure-tenant-id van de klant die uw app wil gebruiken voor toegang tot Defender for Endpoint.

4. Voer de volgende opdracht uit:

   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
   

   U krijgt een antwoord dat lijkt op het volgende codefragment:

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

Het token valideren

Zorg ervoor dat u het juiste token hebt:

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

2. Controleer of u een rolclaim krijgt met de gewenste machtigingen.

   In de volgende afbeelding ziet u een gedecodeerd token dat is verkregen van een app met machtigingen voor alle rollen van Microsoft Defender voor Eindpunt:

   

Het token gebruiken voor toegang tot de Microsoft Defender for Endpoint-API

1. Kies de API die u wilt gebruiken. Zie Ondersteunde Defender voor Eindpunt-API's voor meer informatie.

2. Stel de autorisatieheader in de http aanvraag in Bearer {token} waarnaar u verzendt (Bearer is het autorisatieschema).

3. De verlooptijd van het token is één uur. U kunt meer dan één aanvraag verzenden met hetzelfde token.

Hier volgt een 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

• Ondersteunde API's voor Microsoft Defender voor Eindpunt
• Toegang tot Microsoft Defender voor Eindpunt namens een gebruiker

Tip

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