Använda Api:er för Microsoft Defender för Endpoint

Artikel
06/25/2024

Gäller för:

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
ina.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 till Microsoft Defender för Endpoint utan en användare kan du läsa Åtkomst till Microsoft Defender för Endpoint med programkontext.

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

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 till Microsoft Defender för Endpoint och validerar token.

Obs!

När du öppnar 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 läser du 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

Logga in på Azure-portalen.
Gå till Microsoft Entra ID>Appregistreringar>Ny registrering.

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

Namn – Ange ett beskrivande programnamn som 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 endast Microsoft Entra-klientorganisation. Det här alternativet ä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-konton för flera klientorganisationer och personliga Microsoft-konton.
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-multitenant. Om du har registrerat appen som en enda Microsoft Entra-klientorganisation kan du uppdatera den till Microsoft Entra multitenant 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-konton med flera klientorganisationer och personliga Microsoft-konton. Om du har registrerat appen som Microsoft Entra-konton för flera klientorganisationer och personliga Microsoft-konton kan du inte ändra detta 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.

Ge ditt program åtkomst till Microsoft Defender för Endpoint och tilldela det 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.
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älvstudie om 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

Tips

Vill du veta mer? Interagera med Microsoft Security-communityn i vår Tech Community: Microsoft Defender för Endpoint Tech Community.

Dela via

Använda Api:er för Microsoft Defender för Endpoint

Skapa en app

Hämta en åtkomsttoken

Använda C#

Verifiera token

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

Se även

Feedback

Ytterligare resurser