een app Creatie om toegang te krijgen 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:

• 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 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:

• Creatie een Microsoft Entra-toepassing.
• 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 opgeeft voor Microsoft Defender voor Eindpunt en het token valideert.

een app Creatie

1. Meld u aan bij Azure 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.

   

   U moet de relevante machtigingen selecteren. 'Alle waarschuwingen lezen' is slechts een voorbeeld. Bijvoorbeeld:

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

5. Selecteer Toestemming verlenen.

   Opmerking

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

   

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

   

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

   

8. 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). Uw app instellen op multitenant:

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

   • 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 000000000-0000-0000-00000-0000000000000 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 zelfstudie Microsoft Entra 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. Creatie 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 CLIENT_ID in op uw Azure-toepassings-id.

2. Stel CLIENT_SECRET in op uw Azure-toepassingsgeheim.

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

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 in de volgende vorm:

   {"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 'rollenclaim' 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 om toegang te krijgen tot Microsoft Defender voor Eindpunt 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 die u verzendt in op Bearer {token}(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
• Access Microsoft Defender voor Eindpunt namens een gebruiker

Tip

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