Bruke Microsoft Defender for endepunkt-API-er

Gjelder for:

• Microsoft Defender for endepunkt plan 1
• Microsoft Defender for endepunkt plan 2
• Microsoft Defender for Business

Viktig

Avanserte jaktfunksjoner er ikke inkludert i Defender for Business.

Vil du oppleve Microsoft Defender for endepunkt? Registrer deg for en gratis prøveperiode.

Obs!

Hvis du er us Government-kunde, kan du bruke URI-ene som er oppført i Microsoft Defender for Endpoint for US Government-kunder.

Tips

Hvis du vil ha bedre ytelse, kan du bruke serveren nærmere geografisk plassering:

• us.api.security.microsoft.com
• eu.api.security.microsoft.com
• uk.api.security.microsoft.com
• au.api.security.microsoft.com
• swa.api.security.microsoft.com

Denne siden beskriver hvordan du oppretter et program for å få programmatisk tilgang til Defender for Endpoint på vegne av en bruker.

Hvis du trenger programmatisk tilgang til Microsoft Defender for endepunkt uten en bruker, kan du se Access Microsoft Defender for Endpoint med programkontekst.

Hvis du ikke er sikker på hvilken tilgang du trenger, kan du lese innføringssiden.

Microsoft Defender for Endpoint viser mye av dataene og handlingene gjennom et sett med programmatiske API-er. Disse API-ene gjør det mulig for deg å automatisere arbeidsflyter og innovere basert på Microsoft Defender for Endpoint-funksjoner. API-tilgang krever OAuth2.0-godkjenning. Hvis du vil ha mer informasjon, kan du se OAuth 2.0 Authorization Code Flow.

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

• Opprette et Microsoft Entra-program
• Få et tilgangstoken ved hjelp av dette programmet
• Bruke tokenet til å få tilgang til Defender for endepunkt-API

Denne siden forklarer hvordan du oppretter et Microsoft Entra-program, får et tilgangstoken til Microsoft Defender for Endpoint og validerer tokenet.

Obs!

Når du åpner Microsoft Defender for endepunkt-API på vegne av en bruker, trenger du riktig programtillatelse og brukertillatelse. Hvis du ikke er kjent med brukertillatelser for Microsoft Defender for endepunkt, kan du se Administrere portaltilgang ved hjelp av rollebasert tilgangskontroll.

Tips

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

Opprette en app

1. Logg på Azure-portalen.

2. Naviger til Registreringer> av Microsoft Entra ID-appen>Ny registrering.

   

3. Når siden Registrer et program vises, skriver du inn registreringsinformasjonen for programmet:

   • Navn – Skriv inn et meningsfullt programnavn som vises for brukerne av appen.

   • Støttede kontotyper – Velg hvilke kontoer du vil at programmet skal støtte.

     
     

     Støttede kontotyper	Beskrivelse
     Bare kontoer i denne organisasjonskatalogen	Velg dette alternativet hvis du bygger et bransjeprogram (LOB). Dette alternativet er ikke tilgjengelig hvis du ikke registrerer programmet i en katalog. Dette alternativet tilordnes til én leier som bare gjelder Microsoft Entra. Dette alternativet er standardalternativet med mindre du registrerer appen utenfor en katalog. I tilfeller der appen er registrert utenfor en katalog, er standard Microsoft Entra multitenant- og personlige Microsoft-kontoer.
     Kontoer i alle organisasjonskataloger	Velg dette alternativet hvis du vil målrette mot alle bedriftskunder og utdanningskunder. Dette alternativet tilordnes en microsoft entra-bare multitenant. Hvis du registrerte appen som bare Microsoft Entra-enkeltleier, kan du oppdatere den til å være Microsoft Entra-multitenant og tilbake til én tenant gjennom godkjenningsbladet .
     Kontoer i alle organisasjonskataloger og personlige Microsoft-kontoer	Velg dette alternativet for å målrette mot det bredeste settet med kunder. Dette alternativet tilordnes Microsoft Entra-kontoer for flere enheter og personlige Microsoft-kontoer. Hvis du registrerte appen som Microsoft Entra multitenant- og personlige Microsoft-kontoer, kan du ikke endre dette i brukergrensesnittet. I stedet må du bruke redigeringsprogrammet for programmanifest til å endre kontotypene som støttes.

   • Omdirigerings-URI (valgfritt) – Velg hvilken type app du bygger, nett - eller offentlig klient (mobil & skrivebord), og skriv deretter inn omadresserings-URI-en (eller nettadressen for svar) for programmet.

     • Angi den grunnleggende nettadressen for appen for nettprogrammer. Kan for eksempel http://localhost:31544 være nettadressen for en nettapp som kjører på den lokale maskinen. Brukere bruker denne URL-adressen til å logge på et webklientprogram.

     • For offentlige klientprogrammer kan du oppgi URI-en som brukes av Microsoft Entra ID til å returnere tokensvar. Angi en verdi som er spesifikk for programmet, for eksempel myapp://auth.

     Hvis du vil se spesifikke eksempler for nettprogrammer eller opprinnelige programmer, kan du se hurtigstartene våre.

     Når du er ferdig, velger du Registrer.

4. Gi programmet tilgang til Microsoft Defender for endepunkt og tilordne tillatelsen Lesevarsler:

   • På programsiden velger du API-tillatelser>Legg til tillatelses-API-er>organisasjonen min bruker> , skriver inn WindowsDefenderATP og velger WindowsDefenderATP.

     Obs!

     WindowsDefenderATP vises ikke i den opprinnelige listen. Begynn å skrive navnet i tekstboksen for å se det vises.

     

   • Velg Varsel om delegerte tillatelser.Les>> velg Legg til tillatelser.

     

   Viktig

   Velg de relevante tillatelsene. Lesevarsler er bare et eksempel.

   Eksempel:

   • Hvis du vil kjøre avanserte spørringer, velger du Kjør avanserte spørringer-tillatelse .

   • Hvis du vil isolere en enhet, velger du Isolate-maskintillatelse .

   • Hvis du vil finne ut hvilken tillatelse du trenger, kan du se Tillatelser-delen i API-en du er interessert i å ringe.

   • Velg Gi samtykke.

     Obs!

     Hver gang du legger til tillatelse, må du velge gi samtykke for at den nye tillatelsen skal tre i kraft.

     

5. Skriv ned program-ID-en og leier-ID-en.

   Gå til Oversikt på programsiden, og kopier følgende informasjon:

   

Få et tilgangstoken

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

Bruk av C#

• Kopier/lim inn klassen nedenfor i programmet.

• Bruk Metoden AcquireUserTokenAsync med program-ID, leier-ID, brukernavn og passord for å hente et token.

  namespace WindowsDefenderATP
  {
      using System.Net.Http;
      using System.Text;
      using System.Threading.Tasks;
      using Newtonsoft.Json.Linq;
  
      public static class WindowsDefenderATPUtils
      {
          private const string Authority = "https://login.microsoftonline.com";
  
          private const string WdatpResourceId = "https://api.securitycenter.microsoft.com";
  
          public static async Task<string> AcquireUserTokenAsync(string username, string password, string appId, string tenantId)
          {
              using (var httpClient = new HttpClient())
              {
                  var urlEncodedBody = $"resource={WdatpResourceId}&client_id={appId}&grant_type=password&username={username}&password={password}";
  
                  var stringContent = new StringContent(urlEncodedBody, Encoding.UTF8, "application/x-www-form-urlencoded");
  
                  using (var response = await httpClient.PostAsync($"{Authority}/{tenantId}/oauth2/token", stringContent).ConfigureAwait(false))
                  {
                      response.EnsureSuccessStatusCode();
  
                      var json = await response.Content.ReadAsStringAsync().ConfigureAwait(false);
  
                      var jObject = JObject.Parse(json);
  
                      return jObject["access_token"].Value<string>();
                  }
              }
          }
      }
  }
  

Validere tokenet

Kontroller at du har et riktig token:

• Kopier/lim inn i JWT tokenet du fikk i forrige trinn for å dekode det.

• Valider at du får et «scp»-krav med de ønskede apptillatelsene.

• I skjermbildet nedenfor kan du se et dekodet token hentet fra appen i opplæringen:

  

Bruke tokenet til å få tilgang til Microsoft Defender for endepunkt-API

• Velg API-en du vil bruke – Microsoft Defender for endepunkt-API-er som støttes.

• Angi autorisasjonshodet i HTTP-forespørselen du sender til "Bærer {token}" (Bærer er godkjenningsskjemaet).

• Utløpstiden for tokenet er 1 time (du kan sende mer enn én forespørsel med samme token).

• Eksempel på sending av en forespørsel for å få en liste over varsler ved hjelp av C#:

  var httpClient = new HttpClient();
  
  var request = new HttpRequestMessage(HttpMethod.Get, "https://api.securitycenter.microsoft.com/api/alerts");
  
  request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
  
  var response = httpClient.SendAsync(request).GetAwaiter().GetResult();
  
  // Do something useful with the response
  

Se også

• API-er for Microsoft Defender for endepunkt
• Få tilgang til Microsoft Defender for endepunkt med programkontekst

Tips

Vil du lære mer? Engasjer deg med Microsoft Security-fellesskapet i det tekniske fellesskapet vårt: Microsoft Defender for Endpoint Tech Community.