Opprett en app for å få tilgang til Microsoft Defender XDR API-er på vegne av en bruker

  • Artikkel

Gjelder for:

  • Microsoft Defender XDR

Viktig

Noe informasjon er knyttet til forhåndsutgitt produkt som kan endres vesentlig før det utgis kommersielt. Microsoft gir ingen garantier, uttrykkelige eller underforståtte, med hensyn til informasjonen som er oppgitt her.

Denne siden beskriver hvordan du oppretter et program for å få programmatisk tilgang til Microsoft Defender XDR på vegne av én enkelt bruker.

Hvis du trenger programmatisk tilgang til Microsoft Defender XDR uten en definert bruker (for eksempel hvis du skriver en bakgrunnsapp eller daemon), kan du se Opprett en app for å få tilgang til Microsoft Defender XDR uten en bruker. Hvis du trenger tilgang for flere leiere, for eksempel hvis du betjener en stor organisasjon eller en gruppe kunder, kan du se Opprett en app med partnertilgang til Microsoft Defender XDR API-er. Hvis du ikke er sikker på hvilken type tilgang du trenger, kan du se Komme i gang.

Microsoft Defender XDR viser mye av dataene og handlingene gjennom et sett med programmatiske API-er. Disse API-ene hjelper deg med å automatisere arbeidsflyter og bruke funksjonene til Microsoft Defender XDR. Denne API-tilgangen krever OAuth2.0-godkjenning. Hvis du vil ha mer informasjon, kan du se OAuth 2.0 Authorization Code Flow.

Generelt må du utføre følgende trinn for å bruke disse API-ene:

  • Opprett et Microsoft Entra program.
  • Få et tilgangstoken ved hjelp av dette programmet.
  • Bruk tokenet til å få tilgang Microsoft Defender XDR API.

Denne artikkelen forklarer hvordan du:

  • Opprett et Microsoft Entra program
  • Få et tilgangstoken til Microsoft Defender XDR
  • Validere tokenet

Obs!

Når du åpner Microsoft Defender XDR API på vegne av en bruker, trenger du de riktige programtillatelsene og brukertillatelsene.

Tips

Hvis du har tillatelse til å utføre en handling i portalen, har du tillatelse til å utføre handlingen i API-en.

Opprett en app

  1. Logg deg på Azure som en bruker med rollen global administrator .

  2. Gå til Microsoft Entra ID>App-registreringer>Ny registrering.

    Alternativet Ny registrering i Administrer-ruten i Azure Portal

  3. Velg et navn for programmet i skjemaet, og skriv inn følgende informasjon for omadresserings-URI-en, og velg deretter Registrer.

    Registreringsruten for programmet i Azure Portal

  4. Velg API-tillatelserLegg til tillatelses-API-er>>organisasjonen bruker> på programsiden, skriv inn Microsoft Trusselbeskyttelse og velg Microsoft Trusselbeskyttelse. Appen kan nå få tilgang til Microsoft Defender XDR.

    Tips

    Microsoft Threat Protection er et tidligere navn for Microsoft Defender XDR, og vises ikke i den opprinnelige listen. Du må begynne å skrive navnet i tekstboksen for å se det.

    Organisasjonens API-er-rute i Microsoft Defender-portalen

    • Velg Delegerte tillatelser. Velg de relevante tillatelsene for scenarioet (for eksempel Hendelse.Les), og velg deretter Legg til tillatelser.

      Ruten Delegerte tillatelser i Microsoft Defender-portalen

    Obs!

    Du må velge de relevante tillatelsene for scenarioet. Les alle hendelser er bare et eksempel. Hvis du vil finne ut hvilken tillatelse du trenger, kan du se på Tillatelser-delen i API-en du vil kalle opp.

    Hvis du for eksempel vil kjøre avanserte spørringer, velger du tillatelsen Kjør avanserte spørringer. hvis du vil isolere en enhet, velger du tillatelsen "Isolate machine".

  5. Velg Gi administratorsamtykke. Hver gang du legger til en tillatelse, må du velge Gi administratorsamtykke for at den skal tre i kraft.

    Ruten for samtykketildeling for administratorer i Microsoft Defender-portalen

  6. Registrer program-ID-en og leier-ID-en din et trygt sted. De er oppført under Oversikt på programsiden.

    Oversikt-ruten i Microsoft Defender-portalen

Få et tilgangstoken

Hvis du vil ha mer informasjon om Microsoft Entra tokener, kan du se Microsoft Entra opplæringen.

Få et tilgangstoken på vegne av en bruker ved hjelp av PowerShell

Bruk MSAL.PS-biblioteket til å hente tilgangstokener med delegerte tillatelser. Kjør følgende kommandoer for å få tilgangstoken på vegne av en bruker:

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

Validere tokenet

  1. Kopier og lim inn tokenet i JWT for å dekode det.
  2. Kontroller at rollekravet i det dekodede tokenet inneholder de ønskede tillatelsene.

I illustrasjonen nedenfor kan du se et dekodet token hentet fra en app, med Incidents.Read.All, Incidents.ReadWrite.Allog AdvancedHunting.Read.All tillatelser:

Tillatelser-delen i ruten Dekodede tokener i Microsoft Defender-portalen

Bruke tokenet til å få tilgang til Microsoft Defender XDR-API-en

  1. Velg API-en du vil bruke (hendelser eller avansert jakt). Hvis du vil ha mer informasjon, kan du se Støttede Microsoft Defender XDR API-er.
  2. I http-forespørselen du er i ferd med å sende, setter du autorisasjonshodet til "Bearer" <token>, Bærer er godkjenningsskjemaet og tokenet er det validerte tokenet.
  3. Tokenet utløper innen én time. Du kan sende mer enn én forespørsel i løpet av denne tiden med samme token.

Følgende eksempel viser hvordan du sender en forespørsel om å få en liste over hendelser ved hjelp av 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();

Tips

Vil du lære mer? Kommuniser med Microsoft Sikkerhet-fellesskapet i det tekniske fellesskapet vårt: Microsoft Defender XDR Tech Community.