Bruk Microsoft Defender for endepunkt API-er

  • Artikkel

Gjelder for:

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 endepunkt 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 Microsoft Defender for endepunkt uten en bruker, kan du se Access Microsoft Defender for endepunkt med programkontekst.

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

Microsoft Defender for endepunkt 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 endepunkt funksjoner. API-tilgang 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 API-ene:

  • Opprett 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 for å Microsoft Defender for endepunkt og validere 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 på 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.

Opprett en app

  1. Logg på Azure med en brukerkonto som har rollen global administrator .

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

    Siden for appregistreringer i Microsoft Azure Portal

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

    • Navn – Skriv inn et meningsfullt programnavn som skal 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 Microsoft Entra bare én leier.

      Dette er standardalternativet med mindre du registrerer appen utenfor en katalog. I tilfeller der appen er registrert utenfor en katalog, er standarden Microsoft Entra microsoft-kontoer med flere leiere og personlige.
      Kontoer i alle organisasjonskataloger Velg dette alternativet hvis du vil målrette mot alle bedriftskunder og utdanningskunder.

      Dette alternativet tilordnes til en Microsoft Entra bare flerleier.

      Hvis du registrerte appen som Microsoft Entra bare én leier, kan du oppdatere den slik at den Microsoft Entra flere leiere og gå 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 til Microsoft Entra microsoft-kontoer med flere leiere og personlige kontoer.

      Hvis du registrerte appen som Microsoft Entra microsoft-kontoer med flere leiere og personlige 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.

      • Angi URI-en som brukes av Microsoft Entra ID til å returnere tokensvar for offentlige klientprogrammer. 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.

      legg til tillatelse.

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

      Rutene programtype og 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.

      Alternativet for samtykke for stor administrator

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

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

    Den opprettede app-ID-en

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:

    Tokenvalideringssiden

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

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

  • 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å

Tips

Vil du lære mer? Engage med Microsoft Security-fellesskapet i teknisk fellesskap: Microsoft Defender for endepunkt teknisk fellesskap.