Delen via

Een app maken voor toegang tot Microsoft Defender XDR-API's namens 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 namens één gebruiker.

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. Als u toegang wilt bieden voor meerdere tenants, bijvoorbeeld als u een grote organisatie of een groep klanten bedient, raadpleegt u Een app maken 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:

  • Een Microsoft Entra-toepassing maken.
  • Haal een toegangstoken op met behulp van deze toepassing.
  • Gebruik het token om toegang te krijgen tot de 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

Wanneer u namens een gebruiker toegang krijgt tot de Microsoft Defender XDR-API, 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.

    De optie Nieuwe registratie in het deelvenster Beheren in Azure Portal

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

    Het deelvenster Toepassingsregistratie in Azure 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.

    Het deelvenster API's van uw organisatie in de Microsoft Defender-portal

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

      Het deelvenster Gedelegeerde machtigingen 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.

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

    Het deelvenster Beheerderstoestemming verlenen in de Microsoft Defender-portal

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

Een toegangstoken ophalen

Zie de Microsoft Entra-zelfstudie 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 :

De sectie machtigingen in het deelvenster Gedecodeerde 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? Neem contact op met de Microsoft Security-community in onze Tech Community: Microsoft Defender XDR Tech Community.