Share via

een app Creatie voor toegang tot Microsoft Defender XDR zonder een gebruiker

  • Artikel

Van toepassing op:

  • Microsoft Defender XDR

Belangrijk

Sommige informatie is gerelateerd aan voorlopige productversies die mogelijk aanzienlijk gewijzigd worden voordat ze commercieel gepubliceerd worden. Microsoft geeft geen garantie, uitdrukkelijk of impliciet, met betrekking tot de informatie die hier wordt beschreven.

Op deze pagina wordt beschreven hoe u een toepassing maakt om programmatische toegang te krijgen tot Microsoft Defender XDR zonder een gedefinieerde gebruiker, bijvoorbeeld als u een daemon- of achtergrondservice maakt.

Als u programmatische toegang nodig hebt tot Microsoft Defender XDR namens een of meer gebruikers, raadpleegt u Creatie een app toegang tot Microsoft Defender XDR API's namens een gebruiker en Creatie een app met partnertoegang tot Microsoft Defender XDR API's. Als u niet zeker weet welk type toegang u nodig hebt, raadpleegt u Aan de slag.

Microsoft Defender XDR maakt veel van de gegevens en acties beschikbaar via een set programmatische API's. Met deze API's kunt u werkstromen automatiseren en gebruikmaken van de mogelijkheden van Microsoft Defender XDR. Voor deze 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 deze API's te gebruiken:

  • Creatie een Microsoft Entra-toepassing.
  • Haal een toegangstoken op met behulp van deze toepassing.
  • Gebruik het token om toegang te krijgen tot Microsoft Defender XDR API.

In dit artikel wordt uitgelegd hoe u het volgende kunt doen:

  • een Microsoft Entra-toepassing Creatie
  • Een toegangstoken ophalen voor Microsoft Defender XDR
  • Valideer het token.

een app Creatie

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

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

    Het tabblad Nieuwe registratie in de Microsoft Defender-portal

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

  4. Selecteer op uw toepassingspagina API-machtigingenToevoegenmachtigings-API's >> diemijn organisatie gebruikt>, typ Microsoft Threat Protection en selecteer Microsoft Threat Protection. Uw app heeft nu toegang tot Microsoft Defender XDR.

    Tip

    Microsoft Threat Protection is een voormalige naam voor Microsoft Defender XDR en wordt niet weergegeven in de oorspronkelijke lijst. U moet beginnen met het schrijven van de naam in het tekstvak om deze weer te geven.

    Het tabblad API-gebruik van de organisatie in de Microsoft Defender-portal

  5. Selecteer Toepassingsmachtigingen. Kies de relevante machtigingen voor uw scenario (bijvoorbeeld Incident.Read.All) en selecteer vervolgens Machtigingen toevoegen.

    Het deelvenster met toepassingsmachtigingen in de Microsoft Defender-portal

    Opmerking

    U moet de relevante machtigingen voor uw scenario selecteren. Alle incidenten lezen is slechts een voorbeeld. Als u wilt bepalen welke machtiging u nodig hebt, bekijkt u de sectie Machtigingen in de API die u wilt aanroepen.

    Als u bijvoorbeeld 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.

  6. Selecteer Beheerderstoestemming verlenen. Telkens wanneer u een machtiging toevoegt, moet u Beheerderstoestemming verlenen selecteren om deze van kracht te laten worden.

    Het deelvenster met betrekking tot toestemmingsverlening in de Microsoft Defender-portal

  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.

    Tip

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

    Het deelvenster App maken in de Microsoft Defender-portal

  8. Noteer uw toepassings-id en uw tenant-id ergens veilig. Ze worden weergegeven onder Overzicht op de pagina van uw toepassing.

    Het deelvenster Overzicht in de Microsoft Defender-portal

  9. Alleen voor Microsoft Defender XDR-partners: volg deze instructies voor partnertoegang via de Microsoft Defender XDR API's en stel uw app in op multitenant, zodat deze beschikbaar kan zijn in alle tenants zodra u beheerderstoestemming hebt ontvangen. Partnertoegang is vereist voor apps van derden, bijvoorbeeld als u een app maakt die is bedoeld om te worden uitgevoerd in tenants van meerdere klanten. Dit is niet vereist als u een service maakt die u alleen in uw tenant wilt uitvoeren, zoals een toepassing 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.

    Omdat uw toepassing communiceert met Microsoft Defender XDR namens uw gebruikers, moet deze worden goedgekeurd voor elke tenant waarvoor u deze wilt gebruiken.

    De globale beheerder van Active Directory voor elke tenant moet de toestemmingskoppeling selecteren en uw app goedkeuren.

    De toestemmingskoppeling heeft de volgende structuur:

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

    De cijfers moeten worden vervangen door uw toepassings-id 00000000-0000-0000-0000-000000000000 .

Gereed! U hebt een toepassing 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.

Belangrijk

Hoewel u in de voorbeelden in deze sectie wordt aangemoedigd om geheime waarden te plakken voor testdoeleinden, moet u geheimen nooit hardcoderen in een toepassing die in productie wordt uitgevoerd. Een derde partij kan uw geheim gebruiken om toegang te krijgen tot resources. U kunt de geheimen van uw app beveiligen met behulp van Azure Key Vault. Zie Geheimen in uw server-apps beheren met Azure Key Vault voor een praktisch voorbeeld van hoe u uw app kunt beveiligen.

Een toegangstoken ophalen met Behulp van PowerShell

# This code gets the application context token and saves it to a file named "Latest-token.txt" under the current directory.

$tenantId = '' # Paste your directory (tenant) ID here
$clientId = '' # Paste your application (client) ID here
$appSecret = '' # Paste your own app secret here to test, then store it in a safe place, such as the Azure Key Vault!

$resourceAppIdUri = 'https://api.security.microsoft.com'
$oAuthUri = "https://login.windows.net/$tenantId/oauth2/token"

$authBody = [Ordered] @{
    resource = $resourceAppIdUri
    client_id = $clientId
    client_secret = $appSecret
    grant_type = 'client_credentials'
}

$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token

Out-File -FilePath "./Latest-token.txt" -InputObject $token

return $token

Een toegangstoken ophalen met C#

Opmerking

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 de volgende regel toe:

    using Microsoft.Identity.Client;

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

    csharp
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;

Een toegangstoken ophalen met python

import json
import urllib.request
import urllib.parse

tenantId = '' # Paste your directory (tenant) ID here
clientId = '' # Paste your application (client) ID here
appSecret = '' # Paste your own app secret here to test, then store it in a safe place, such as the Azure Key Vault!

url = "https://login.windows.net/%s/oauth2/token" % (tenantId)

resourceAppIdUri = 'https://api.security.microsoft.com'

body = {
    'resource' : resourceAppIdUri,
    'client_id' : clientId,
    'client_secret' : appSecret,
    'grant_type' : 'client_credentials'
}

data = urllib.parse.urlencode(body).encode("utf-8")

req = urllib.request.Request(url, data)
response = urllib.request.urlopen(req)
jsonResponse = json.loads(response.read())
aadToken = jsonResponse["access_token"]

Een toegangstoken ophalen met curl

Opmerking

Curl is vooraf geïnstalleerd op Windows 10 versie 1803 en hoger. Voor andere versies van Windows downloadt en installeert u het hulpprogramma rechtstreeks vanaf de officiële curl-website.

  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 Microsoft Defender XDR.

  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://api.security.microsoft.com/.default" -d "client_secret=%CLIENT_SECRET%" "https://login.microsoftonline.com/%TENANT_ID%/oauth2/v2.0/token" -k

    Een geslaagd antwoord ziet er als volgt uit:

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

Het token valideren

  1. Kopieer en plak het token in de JSON-webtokenvalidatorwebsite, JWT, om het te decoderen.

  2. Zorg ervoor dat de rollenclaim binnen het gedecodeerde token de gewenste machtigingen bevat.

    In de volgende afbeelding ziet u een gedecodeerd token dat is verkregen uit een app, met Incidents.Read.Allmachtigingen , Incidents.ReadWrite.Allen AdvancedHunting.Read.All :

    Het deelvenster Gedecodeerd token in de Microsoft Defender-portal

Het token gebruiken voor toegang tot de Microsoft Defender XDR-API

  1. Kies de API die u wilt gebruiken (incidenten of geavanceerde opsporing). Zie Ondersteunde Microsoft Defender XDR API's voor meer informatie.

  2. Stel in de HTTP-aanvraag die u gaat verzenden de autorisatieheader in op "Bearer" <token>, Bearer is het autorisatieschema en token uw gevalideerde token.

  3. Het token verloopt binnen een uur. U kunt in deze periode meer dan één aanvraag verzenden met hetzelfde token.

In het volgende voorbeeld ziet u hoe u een aanvraag verzendt om een lijst met incidenten op te halen met behulp van C#.

    var httpClient = new HttpClient();
    var request = new HttpRequestMessage(HttpMethod.Get, "https://api.security.microsoft.com/api/incidents");

    request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

    var response = httpClient.SendAsync(request).GetAwaiter().GetResult();

Tip

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