Een app maken met partnertoegang tot Microsoft Defender XDR API's

  • Artikel

Opmerking

Wilt u Microsoft Defender XDR ervaren? Meer informatie over hoe u Microsoft Defender XDR kunt evalueren en piloten.

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 Microsoft Entra-app maakt die programmatisch toegang heeft tot Microsoft Defender XDR, namens gebruikers in meerdere tenants. Apps met meerdere tenants zijn handig voor het bedienen van grote groepen gebruikers.

Als u programmatische toegang nodig hebt tot Microsoft Defender XDR namens één gebruiker, raadpleegt u Een app maken voor toegang tot Microsoft Defender XDR API's namens een gebruiker. Als u toegang nodig hebt zonder dat een gebruiker expliciet is gedefinieerd (bijvoorbeeld als u een achtergrond-app of daemon schrijft), raadpleegt u Een app maken voor toegang tot Microsoft Defender XDR zonder een gebruiker. 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:

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

Omdat deze app meerdere tenants is, hebt u ook beheerderstoestemming van elke tenant nodig namens de gebruikers.

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

  • Een Microsoft Entra-toepassing met meerdere tenants maken
  • Vraag geautoriseerde toestemming van uw gebruikersbeheerder voor uw toepassing om toegang te krijgen tot de Microsoft Defender XDR die resources nodig zijn.
  • Een toegangstoken ophalen voor Microsoft Defender XDR
  • Het token valideren

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 innoveren op basis van Microsoft Defender XDR 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:

  • Maak een Microsoft Entra-toepassing met meerdere tenants.
  • Krijg toestemming (toestemming) van uw gebruikersbeheerder voor uw toepassing om toegang te krijgen tot Microsoft Defender XDR resources die deze nodig heeft.
  • Haal een toegangstoken op met behulp van deze toepassing.
  • Gebruik het token om toegang te krijgen tot Microsoft Defender XDR API.

De volgende stappen met hulp bij het maken van een toepassing met meerdere tenants Microsoft Entra, het ophalen van een toegangstoken voor Microsoft Defender XDR en het valideren van het token.

De app voor meerdere tenants maken

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

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

    De sectie registratie van een toepassing in de Microsoft Defender-portal

  3. In het registratieformulier:

    • Kies een naam voor uw toepassing.
    • Selecteer in Ondersteunde accounttypende optie Accounts in een organisatiemap (Elke Microsoft Entra directory) - Multitenant.
    • Vul de sectie Omleidings-URI in. Selecteer Web en geef de omleidings-URI op als https://portal.azure.com.

    Nadat u het formulier hebt ingevuld, selecteert u Registreren.

    De registratiesecties van een toepassing in de Microsoft Defender-portal

  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.

    De sectie API's gebruik 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 machtigingsvenster van een toepassing 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.

    Een sectie voor het verlenen van beheerderstoestemming 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.

    De sectie Geheime toevoeging 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. Voeg de toepassing toe aan de tenant van uw gebruiker.

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

    Een globale beheerder van de tenant van uw gebruiker moet de toestemmingskoppeling bekijken en uw toepassing goedkeuren.

    Toestemmingskoppeling heeft de volgende vorm:

    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 .

    Nadat u op de toestemmingskoppeling hebt geklikt, meldt u zich aan bij de globale beheerder van de tenant van de gebruiker en geeft u toestemming voor de toepassing.

    De pagina van de toestemmingstoepassing in de Microsoft Defender-portal

    U moet uw gebruiker ook om de tenant-id vragen. De tenant-id is een van de id's die worden gebruikt om toegangstokens te verkrijgen.

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

Tip

Gebruik in de volgende voorbeelden de tenant-id van een gebruiker om te testen of het script werkt.

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!

$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. Maak 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):

    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 gebruiker 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://securitycenter.onmicrosoft.com/windowsatpservice/.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 Gedecoded 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.