Create en app for at få adgang til Microsoft Defender for Endpoint uden en bruger

Gælder for:

• Microsoft Defender for Endpoint Plan 1
• Microsoft Defender for Endpoint Plan 2
• Microsoft Defender for Business

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 uden en bruger. Hvis du har brug for programmatisk adgang til Defender for Endpoint på vegne af en bruger, skal du se Få adgang med brugerkontekst. Hvis du ikke er sikker på, hvilken adgang du har brug for, skal du se Kom i gang.

Microsoft Defender for Endpoint fremviser mange af dataene og handlingerne via et sæt programmatiske API'er. Disse API'er hjælper dig med at automatisere arbejdsflow og skabe innovation baseret på funktionerne i Defender for Endpoint. 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:

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

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

Create en app

1. Log på Azure med en bruger, der har rollen Global administrator .

2. Gå til Microsoft Entra ID>Appregistreringer>Ny registrering.

   

3. Vælg et navn til din ansøgning i registreringsformularen, og vælg derefter Registrer.

4. Hvis du vil give din app adgang til Defender for Endpoint og tildele den tilladelsen "Læs alle beskeder", skal du vælge API-tilladelser>TilføjtilladelseS-API'er>, som min organisation bruger>, skrive WindowsDefenderATP og derefter vælge WindowsDefenderATP.

   Bemærk!

   WindowsDefenderATP vises ikke på den oprindelige liste. Begynd at skrive navnet i tekstfeltet for at se det blive vist.

   

   Vælg Programtilladelser>Alert.Read.All, og vælg derefter Tilføj tilladelser.

   

   Du skal vælge de relevante tilladelser. 'Læs alle beskeder' er kun et eksempel. Det kan f.eks. være:

   • Hvis du vil køre avancerede forespørgsler, skal du vælge tilladelsen 'Kør avancerede forespørgsler'.
   • Hvis du vil isolere en enhed, skal du vælge tilladelsen "Isoler computer".
   • 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 kalde.

5. Vælg Giv samtykke.

   Bemærk!

   Hver gang du tilføjer en tilladelse, skal du vælge Giv samtykke , for at den nye tilladelse træder i kraft.

   

6. Hvis du vil føje en hemmelighed til programmet, skal du vælge Certifikater & hemmeligheder, føje en beskrivelse til hemmeligheden og derefter vælge Tilføj.

   Bemærk!

   Når du har valgt Tilføj, skal du vælge kopiér den genererede værdi for hemmelighed. Du kan ikke hente denne værdi, når du er gået.

   

7. Skriv dit program-id og dit lejer-id ned. Gå til Oversigt på din programside, og kopiér følgende.

   

8. Kun for Microsoft Defender for Endpoint partnere. Angiv, at din app skal have flere lejere (tilgængelig i alle lejere efter samtykke). Dette er påkrævet for tredjepartsapps (hvis du f.eks. opretter en app, der er beregnet til at køre i flere kunders lejer). Dette er ikke påkrævet , hvis du opretter en tjeneste, som du kun vil køre i din lejer (hvis du f.eks. opretter et program til dit eget forbrug, der kun interagerer med dine egne data). Sådan angiver du, at din app skal have flere lejere:

   • Gå til Godkendelse, og tilføj https://portal.azure.com som omdirigerings-URI'en.

   • Nederst på siden under Understøttede kontotyper skal du vælge Konti i alle organisationsmappeprogrammers samtykke til din app med flere lejere.

   Du skal have dit program godkendt i hver lejer, hvor du vil bruge det. Det skyldes, at dit program interagerer med Defender for Endpoint på vegne af din kunde.

   Du (eller din kunde, hvis du skriver en tredjepartsapp) skal vælge samtykkelinket og godkende din app. Samtykket skal udføres med en bruger, der har administrative rettigheder i Active Directory.

   Samtykkelinket er udformet på følgende måde:

   https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true
   

   Hvor 00000000-0000-0000-0000-00000000000 erstattes med dit program-id.

Gjort! Du har registreret et program! Se eksempler nedenfor for at få oplysninger om tokenerhvervelse og -validering.

Hent et adgangstoken

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

Brug PowerShell

# This script acquires the App Context Token and stores it in the variable $token for later use in the script.
# Paste your Tenant ID, App ID, and App Secret (App key) into the indicated quotes below.

$tenantId = '' ### Paste your tenant ID here
$appId = '' ### Paste your Application ID here
$appSecret = '' ### Paste your Application key here

$sourceAppIdUri = 'https://api.securitycenter.microsoft.com/.default'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/v2.0/token"
$authBody = [Ordered] @{
    scope = "$sourceAppIdUri"
    client_id = "$appId"
    client_secret = "$appSecret"
    grant_type = 'client_credentials'
}
$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token
$token

Brug C#:

Følgende kode blev testet med NuGet Microsoft.Identity.Client 3.19.8.

Vigtigt!

NuGet-pakken Microsoft.IdentityModel.Clients.ActiveDirectory og ADAL (Azure AD Authentication Library) frarådes. Der er ikke tilføjet nye funktioner siden den 30. juni 2020. Vi opfordrer dig på det kraftigste til at opgradere, se migreringsvejledningen for at få flere oplysninger.

1. Create et nyt konsolprogram.

2. Installér NuGet Microsoft.Identity.Client.

3. Tilføj følgende:

   using Microsoft.Identity.Client;
   

4. Kopiér og indsæt følgende kode i din app (glem ikke at opdatere de tre variabler: tenantId, appId, appSecret):

   string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here
   string appId = "11111111-1111-1111-1111-111111111111"; // Paste your own app ID here
   string appSecret = "22222222-2222-2222-2222-222222222222"; // Paste your own app secret here for a test, and then store it in a safe place! 
   const string authority = "https://login.microsoftonline.com";
   const string audience = "https://api.securitycenter.microsoft.com";
   
   IConfidentialClientApplication myApp = ConfidentialClientApplicationBuilder.Create(appId).WithClientSecret(appSecret).WithAuthority($"{authority}/{tenantId}").Build();
   
   List<string> scopes = new List<string>() { $"{audience}/.default" };
   
   AuthenticationResult authResult = myApp.AcquireTokenForClient(scopes).ExecuteAsync().GetAwaiter().GetResult();
   
   string token = authResult.AccessToken;
   

Brug Python

Se Hent token ved hjælp af Python.

Brug krøllede

Bemærk!

I følgende procedure antages det, at Curl til Windows allerede er installeret på computeren.

1. Åbn en kommandoprompt, og angiv CLIENT_ID til dit Azure-program-id.

2. Angiv CLIENT_SECRET til din Azure-programhemmelighed.

3. Angiv TENANT_ID til Azure-lejer-id'et for den kunde, der vil bruge din app til at få adgang til Defender for Endpoint.

4. Kør følgende kommando:

   curl -i -X POST -H "Content-Type:application/x-www-form-urlencoded" -d "grant_type=client_credentials" -d "client_id=%CLIENT_ID%" -d "scope=https://securitycenter.onmicrosoft.com/windowsatpservice/.default" -d "client_secret=%CLIENT_SECRET%" "https://login.microsoftonline.com/%TENANT_ID%/oauth2/v2.0/token" -k
   

   Du får et svar i følgende form:

   {"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn <truncated> aWReH7P0s0tjTBX8wGWqJUdDA"}
   

Valider tokenet

Sørg for, at du har det korrekte token:

1. Kopiér og indsæt det token, du fik i det forrige trin, i JWT for at afkode det.

2. Valider, at du får et krav om "roller" med de ønskede tilladelser.

   På følgende billede kan du se et afkodet token, der er hentet fra en app med tilladelser til alle Microsoft Defender for Endpoint roller:

   

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

1. Vælg den API, du vil bruge. Du kan finde flere oplysninger under Understøttet Defender for Endpoint-API'er.
2. Angiv godkendelsesheaderen i den http-anmodning, du sender til "Ihændehaver {token}" (Ihændehaver er godkendelsesskemaet).
3. Tokenets udløbstid er én time. Du kan sende mere end én anmodning med det samme token.

Følgende er et eksempel på afsendelse af en anmodning om at få 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å

• Understøttede Microsoft Defender for Endpoint API'er
• Adgang Microsoft Defender for Endpoint på vegne af en bruger

Tip

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