Brug Microsoft Defender til slutpunkt-API'er

Artikel
06/25/2024

Gælder for:

Vigtigt!

Avancerede jagtegenskaber er ikke inkluderet i Defender for Business.

Vil du opleve Microsoft Defender for Endpoint? Tilmeld dig en gratis prøveversion.

Bemærk!

Hvis du er us government-kunde, skal du bruge de URI'er, der er angivet i Microsoft Defender for Endpoint for US Government-kunder.

Tip

For at opnå en bedre ydeevne kan du bruge serveren tættere på din geografiske placering:

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

På denne side beskrives det, hvordan du opretter et program for at få programmatisk adgang til Defender for Endpoint på vegne af en bruger.

Hvis du har brug for programadgang til Microsoft Defender for Endpoint uden en bruger, skal du se Access Microsoft Defender for Endpoint med programkontekst.

Hvis du ikke er sikker på, hvilken adgang du har brug for, kan du læse siden Introduktion.

Microsoft Defender for Endpoint fremviser mange af sine data og handlinger via et sæt programmatiske API'er. Disse API'er gør det muligt for dig at automatisere arbejdsflow og skabe innovation baseret på Microsoft Defender for Endpoint-funktioner. API-adgangen kræver OAuth2.0-godkendelse. Du kan få flere oplysninger under OAuth 2.0 Authorization Code Flow.

Generelt skal du gøre følgende for at bruge API'erne:

Opret et Microsoft Entra-program
Hent et adgangstoken ved hjælp af dette program
Brug tokenet til at få adgang til Defender for Endpoint API

På denne side forklares det, hvordan du opretter et Microsoft Entra-program, får et adgangstoken til Microsoft Defender for Endpoint og validerer tokenet.

Bemærk!

Når du får adgang til Microsoft Defender for Endpoint API på vegne af en bruger, skal du have den korrekte programtilladelse og brugertilladelse. Hvis du ikke kender brugertilladelser til Microsoft Defender for Endpoint, skal du se Administrer portaladgang ved hjælp af rollebaseret adgangskontrol.

Tip

Hvis du har tilladelse til at udføre en handling på portalen, har du tilladelse til at udføre handlingen i API'en.

Opret en app

Log på portalenAzure.
Gå til Microsoft Entra ID>App registrations>Ny registrering.

Når siden Registrer et program vises, skal du angive registreringsoplysningerne for dit program:

Navn – Angiv et sigende programnavn, der vises for brugerne af appen.

Understøttede kontotyper – Vælg, hvilke konti dit program skal understøtte.

Understøttede kontotyper	Beskrivelse
Kun konti i denne organisationsmappe	Vælg denne indstilling, hvis du opretter et line of business-program (LOB). Denne indstilling er ikke tilgængelig, hvis du ikke registrerer programmet i en mappe. Denne indstilling knyttes til kun Microsoft Entra-enkeltlejer. Denne indstilling er standardindstillingen, medmindre du registrerer appen uden for en mappe. I de tilfælde, hvor appen er registreret uden for en mappe, er standarden Microsoft Entra multitenant- og personlige Microsoft-konti.
Konti i en hvilken som helst organisationsmappe	Vælg denne indstilling, hvis du vil målrette mod alle forretnings- og uddannelseskunder. Denne indstilling knyttes til et multitenant, der kun er til Microsoft Entra. Hvis du har registreret appen som enkeltlejer kun til Microsoft Entra, kan du opdatere den til at være Microsoft Entra multitenant og tilbage til enkeltlejer via bladet Godkendelse .
Konti i en hvilken som helst organisationsmappe og personlige Microsoft-konti	Vælg denne indstilling for at målrette det bredeste sæt kunder. Denne indstilling er knyttet til Microsoft Entra-multitenant- og personlige Microsoft-konti. Hvis du har registreret appen som Microsoft Entra multitenant- og personlige Microsoft-konti, kan du ikke ændre dette i brugergrænsefladen. Du skal i stedet bruge programmanifesteditoren til at ændre de understøttede kontotyper.

Omdiriger URI (valgfrit) – Vælg den type app, du bygger, webklient eller offentlig klient (mobil & desktop), og angiv derefter omdirigerings-URI'en (eller svar-URL-adressen) for dit program.
- I forbindelse med webprogrammer skal du angive den grundlæggende URL-adresse til din app. Det kan f.eks. være URL-adressen til en webapp, http://localhost:31544 der kører på din lokale computer. Brugerne skal bruge denne URL-adresse til at logge på et webklientprogram.
- I forbindelse med offentlige klientprogrammer skal du angive den URI, der bruges af Microsoft Entra ID, til at returnere tokensvar. Angiv en værdi, der er specifik for dit program, f.eks myapp://auth. .
Hvis du vil se specifikke eksempler på webprogrammer eller oprindelige programmer, kan du se vores hurtige introduktioner.

Når du er færdig, skal du vælge Registrer.

Tillad, at dit program får adgang til Microsoft Defender for Endpoint, og tildel det tilladelsen "Læs beskeder":
- På din programside skal du vælge API-tilladelser>TilføjtilladelseS-API'er, som min organisation bruger>, skriver WindowsDefenderATP og vælger på WindowsDefenderATP.>
  
  Bemærk!
  
  WindowsDefenderATP vises ikke på den oprindelige liste. Begynd at skrive navnet i tekstfeltet for at se det blive vist.
- Vælg Delegerede tilladelser>Besked.Læs> vælg Tilføj tilladelser.
Vigtigt!

Vælg de relevante tilladelser. Læs beskeder er kun et eksempel.

Det kan f.eks. være:
- Hvis du vil køre avancerede forespørgsler, skal du vælge Kør tilladelse til avancerede forespørgsler .
- Hvis du vil isolere en enhed, skal du vælge Isoler computertilladelse .
- Hvis du vil finde ud af, hvilken tilladelse du har brug for, skal du se afsnittet Tilladelser i den API, du er interesseret i at ringe til.
- Vælg Giv samtykke.
  
  Bemærk!
  
  Hver gang du tilføjer tilladelse, skal du vælge Giv samtykke , for at den nye tilladelse træder i kraft.
Skriv dit program-id og dit lejer-id ned.

Gå til Oversigt på din programside, og kopiér følgende oplysninger:

Hent et adgangstoken

Du kan få flere oplysninger om Microsoft Entra-tokens i Microsoft Entra-selvstudium.

Brug af C#

Kopiér/indsæt klassen nedenfor i dit program.

Brug metoden AcquireUserTokenAsync med dit program-id, lejer-id, brugernavn og adgangskode for at 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>();
                }
            }
        }
    }
}

Valider tokenet

Kontrollér, at du har fået et korrekt token:

Kopiér/indsæt i JWT det token, du fik i det forrige trin, for at afkode det.
Valider, at du får et 'scp'-krav med de ønskede apptilladelser.
På skærmbilledet nedenfor kan du se et afkodet token, der er hentet fra appen, i selvstudiet:

Brug tokenet til at få adgang til Microsoft Defender for Endpoint API

Vælg den API, du vil bruge – Understøttet Microsoft Defender for Endpoint-API'er.
Angiv godkendelsesheaderen i den HTTP-anmodning, du sender til "Ihændehaver {token}" (ihændehaver er autorisationsskemaet).
Tokenets udløbstid er 1 time (du kan sende mere end én anmodning med det samme token).

Eksempel på afsendelse af en anmodning om at få vist en liste over beskeder ved hjælp af 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å

Tip

Vil du vide mere? Kontakt Microsoft Security-community'et i vores Tech Community: Microsoft Defender for Endpoint Tech Community.

Del via