Använda Microsoft Defender för Endpoint-API:er

Gäller för:

• Microsoft Defender för Endpoint Abonnemang 1
• Microsoft Defender för Endpoint Abonnemang 2
• Microsoft Defender för företag

Viktigt

Avancerade jaktfunktioner ingår inte i Defender för företag.

Vill du uppleva Microsoft Defender för Endpoint? Registrera dig för en kostnadsfri utvärderingsversion.

Obs!

Om du är en us government-kund använder du de URI:er som anges i Microsoft Defender för Endpoint för amerikanska myndighetskunder.

Tips

För bättre prestanda kan du använda servern närmare din geoplats:

• 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

Den här sidan beskriver hur du skapar ett program för att få programmatisk åtkomst till Defender för Endpoint för en användares räkning.

Om du behöver programmatisk åtkomst Microsoft Defender för Endpoint utan användare kan du läsa Access Microsoft Defender för Endpoint med programkontext.

Om du inte är säker på vilken åtkomst du behöver kan du läsa introduktionssidan.

Microsoft Defender för Endpoint exponerar mycket av sina data och åtgärder via en uppsättning programmatiska API:er. Med dessa API:er kan du automatisera arbetsflöden och innovationer baserat på Microsoft Defender för Endpoint funktioner. API-åtkomsten kräver OAuth2.0-autentisering. Mer information finns i OAuth 2.0 Authorization Code Flow (OAuth 2.0-auktoriseringskodflöde).

I allmänhet måste du vidta följande steg för att använda API:erna:

• Skapa ett Microsoft Entra program
• Hämta en åtkomsttoken med det här programmet
• Använda token för att komma åt Defender för Endpoint API

Den här sidan beskriver hur du skapar ett Microsoft Entra program, hämtar en åtkomsttoken för att Microsoft Defender för Endpoint och verifiera token.

Obs!

När du använder Microsoft Defender för Endpoint API för en användares räkning behöver du rätt programbehörighet och användarbehörighet. Om du inte är bekant med användarbehörigheter på Microsoft Defender för Endpoint kan du läsa Hantera portalåtkomst med rollbaserad åtkomstkontroll.

Tips

Om du har behörighet att utföra en åtgärd i portalen har du behörighet att utföra åtgärden i API:et.

Skapa en app

1. Logga in på Azure med ett användarkonto som har rollen Global administratör .

2. Gå till Microsoft Entra ID>Appregistreringar>Ny registrering.

   

3. När sidan Registrera ett program visas anger du programmets registreringsinformation:

   • Namn – Ange ett beskrivande programnamn som ska visas för appens användare.

   • Kontotyper som stöds – Välj vilka konton som du vill att programmet ska stödja.

     
     

     Kontotyper som stöds	Beskrivning
     Endast konton i den här organisationskatalogen	Välj det här alternativet om du skapar ett verksamhetsspecifikt program (LOB). Det här alternativet är inte tillgängligt om du inte registrerar programmet i en katalog. Det här alternativet mappar till Microsoft Entra enda klientorganisation. Det här är standardalternativet om du inte registrerar appen utanför en katalog. I fall där appen är registrerad utanför en katalog är standardinställningen Microsoft Entra Microsoft-konton med flera klientorganisationer och personliga.
     Konton i valfri organisationskatalog	Välj det här alternativet om du vill rikta in dig på alla företags- och utbildningskunder. Det här alternativet mappar till en Microsoft Entra endast flera klientorganisationer. Om du har registrerat appen som Microsoft Entra enskild klientorganisation kan du uppdatera den så att den Microsoft Entra flera klientorganisationer och tillbaka till en enskild klient via bladet Autentisering.
     Konton i valfri organisationskatalog och personliga Microsoft-konton	Välj det här alternativet för att rikta in dig på den bredaste uppsättningen kunder. Det här alternativet mappar till Microsoft Entra Microsoft-konton för flera innehavare och personliga Microsoft-konton. Om du har registrerat appen som Microsoft Entra Microsoft-konton för flera innehavare och personliga, kan du inte ändra den i användargränssnittet. I stället måste du använda programmanifestredigeraren för att ändra de kontotyper som stöds.

   • Omdirigerings-URI (valfritt) – Välj den typ av app som du skapar, Webb eller Offentlig klient (mobil & skrivbord) och ange sedan omdirigerings-URI (eller svars-URL) för ditt program.

     • För webbprogram anger du bas-URL:en för din app. Kan till exempel http://localhost:31544 vara URL:en för en webbapp som körs på den lokala datorn. Användarna skulle använda den här URL:en för att logga in på ett webbklientprogram.

     • För offentliga klientprogram anger du den URI som används av Microsoft Entra ID för att returnera tokensvar. Ange ett värde som är specifikt för ditt program, till exempel myapp://auth.

     Om du vill se specifika exempel för webbprogram eller interna program kan du läsa våra snabbstarter.

     När du är klar väljer du Registrera.

4. Ge ditt program åtkomst till Microsoft Defender för Endpoint och tilldela behörigheten Läs aviseringar:

   • På programsidan väljer du API-behörigheter>Lägg till behörighets-API>:er som min organisation använder skriver>WindowsDefenderATP och väljer på WindowsDefenderATP.

     Obs!

     WindowsDefenderATP visas inte i den ursprungliga listan. Börja skriva dess namn i textrutan för att se det visas.

     

   • Välj Avisering om delegerade behörigheter.Läs>> och välj Lägg till behörigheter.

     

   Viktigt

   Välj relevanta behörigheter. Läsaviseringar är bara ett exempel.

   Till exempel:

   • Om du vill köra avancerade frågor väljer du Kör behörighet för avancerade frågor .

   • Om du vill isolera en enhet väljer du Isolera datorbehörighet .

   • Om du vill ta reda på vilken behörighet du behöver kan du läsa avsnittet Behörigheter i det API som du är intresserad av att anropa.

   • Välj Bevilja medgivande.

     Obs!

     Varje gång du lägger till behörighet måste du välja Bevilja medgivande för att den nya behörigheten ska börja gälla.

     

5. Skriv ned ditt program-ID och ditt klientorganisations-ID.

   På programsidan går du till Översikt och kopierar följande information:

   

Hämta en åtkomsttoken

Mer information om Microsoft Entra-token finns i självstudien Microsoft Entra.

Använda C#

• Kopiera/klistra in klassen nedan i ditt program.

• Använd metoden AcquireUserTokenAsync med ditt program-ID, klientorganisations-ID, användarnamn och lösenord för att hämta en 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>();
                  }
              }
          }
      }
  }
  

Verifiera token

Kontrollera att du har rätt token:

• Kopiera/klistra in den token som du fick i föregående steg i JWT för att avkoda den.

• Verifiera att du får ett "scp"-anspråk med önskade appbehörigheter.

• I skärmbilden nedan kan du se en avkodad token som hämtats från appen i självstudien:

  

Använda token för att komma åt Microsoft Defender för Endpoint API

• Välj det API som du vill använda – MICROSOFT DEFENDER FÖR ENDPOINT API:er som stöds.

• Ange auktoriseringshuvudet i HTTP-begäran som du skickar till "Bearer {token}" (Ägaren är auktoriseringsschemat).

• Förfallotiden för token är 1 timme (du kan skicka fler än en begäran med samma token).

• Exempel på hur du skickar en begäran om att hämta en lista över aviseringar med hjälp 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 även

• Microsoft Defender för Endpoint API:er
• Åtkomst Microsoft Defender för Endpoint med programkontext

Tips

Vill du veta mer? Engage med Microsofts säkerhetscommunity i vår Tech Community: Microsoft Defender för Endpoint Tech Community.