Een app maken voor toegang tot Microsoft Defender XDR API's namens een gebruiker

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 namens één gebruiker een toepassing maakt om programmatische toegang te krijgen tot Microsoft Defender XDR.

Als u programmatische toegang nodig hebt tot Microsoft Defender XDR zonder een gedefinieerde gebruiker (bijvoorbeeld als u een achtergrond-app of daemon schrijft), raadpleegt u Een app maken voor toegang tot Microsoft Defender XDR zonder een gebruiker. Zie Een app maken met partnertoegang tot Microsoft Defender XDR API's als u toegang wilt bieden voor meerdere tenants, bijvoorbeeld als u een grote organisatie of een groep klanten bedient. 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.

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

• Een Microsoft Entra-toepassing maken
• Een toegangstoken ophalen voor Microsoft Defender XDR
• Het token valideren

Opmerking

Bij het openen van Microsoft Defender XDR API namens een gebruiker, hebt u de juiste toepassingsmachtigingen en gebruikersmachtigingen nodig.

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

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

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

   

3. Kies in het formulier een naam voor uw toepassing, voer de volgende informatie in voor de omleidings-URI en selecteer vervolgens Registreren.

   

   • Toepassingstype: Openbare client
   • Omleidings-URI:https://portal.azure.com

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.

   

   • Kies Gedelegeerde machtigingen. Kies de relevante machtigingen voor uw scenario (bijvoorbeeld Incident.Read) en selecteer vervolgens Machtigingen toevoegen.

     

   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.

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

   

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

   

Een toegangstoken ophalen

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

Een toegangstoken ophalen namens een gebruiker met behulp van PowerShell

Gebruik de MSAL.PS-bibliotheek om toegangstokens met gedelegeerde machtigingen te verkrijgen. Voer de volgende opdrachten uit om namens een gebruiker toegangstoken op te halen:

Install-Module -Name MSAL.PS # Install the MSAL.PS module from PowerShell Gallery

$TenantId = " " # Paste your directory (tenant) ID here.
$AppClientId="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # Paste your application (client) ID here.

$MsalParams = @{
   ClientId = $AppClientId
   TenantId = $TenantId
   Scopes   = 'https://graph.microsoft.com/User.Read.All','https://graph.microsoft.com/Files.ReadWrite','https://api.securitycenter.windows.com/AdvancedQuery.Read'
}

$MsalResponse = Get-MsalToken @MsalParams
$AccessToken  = $MsalResponse.AccessToken
 
$AccessToken # Display the token in PS console

Het token valideren

1. Kopieer en plak het token in 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 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();

Verwante artikelen

• Overzicht van Microsoft Defender XDR API's
• Toegang tot de Microsoft Defender XDR API's
• Een app 'Hello wereld' maken
• Een app maken voor toegang tot Microsoft Defender XDR zonder een gebruiker
• Een app maken met partnertoegang met meerdere tenants tot Microsoft Defender XDR API's
• Meer informatie over API-limieten en -licenties
• Foutcodes begrijpen
• OAuth 2.0-autorisatie voor gebruikersaanmelding en API-toegang

Tip

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