Partneradgang via Microsoft Defender for Endpoint API'er

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 til virksomheder.

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
• ina.api.security.microsoft.com

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

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 arbejdsflows 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:

1. Opret et Microsoft Entra program med flere lejere.

2. Få godkendt(samtykke) af din kundeadministrator, så dit program kan få adgang til Defender for Endpoint-ressourcer, det har brug for.

3. Hent et adgangstoken ved hjælp af dette program.

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

Følgende trin hjælper dig med at oprette et Microsoft Entra program, hente et adgangstoken for at Microsoft Defender for Endpoint og validere tokenet.

Vigtigt!

Microsoft anbefaler, at du bruger roller med færrest tilladelser. Dette hjælper med at forbedre sikkerheden for din organisation. Global administrator er en yderst privilegeret rolle, der bør være begrænset til nødsituationer, når du ikke kan bruge en eksisterende rolle.

Opret multitenantappen

1. Log på din Azure-lejer.

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

   

3. I registreringsformularen:

   • Vælg et navn til programmet.

   • Understøttede kontotyper – konti i en hvilken som helst organisationsmappe.

   • Omdirigerings-URI – type: Web, URI: https://portal.azure.com

     

4. Tillad, at dit program får adgang til Microsoft Defender for Endpoint, og tildel det med det minimale sæt tilladelser, der kræves for at fuldføre integrationen.

   • På din programside skal du vælge API-tilladelser>TilføjtilladelseS-API'er, som min organisation bruger>, skriver WindowsDefenderATP og vælger på WindowsDefenderATP.>

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

     

Anmod om API-tilladelser

Hvis du vil finde ud af, hvilken tilladelse du har brug for, skal du gennemse afsnittet Tilladelser i den API, du vil kalde. For eksempel:

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

I følgende eksempel bruger vi tilladelsen Læs alle beskeder :

1. Vælg Programtilladelser>Alert.Read.All> vælg Tilføj tilladelser

   

2. Vælg Tildel samtykke

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

   

3. Føj en hemmelighed til programmet.

   • Vælg Certifikater & hemmeligheder, føj en beskrivelse til hemmeligheden, og vælg Tilføj.

   Når du har valgt Tilføj, skal du sørge for at kopiere den genererede værdi for hemmelighed. Du kan ikke hente den, når du er gået!

   

4. Skriv dit program-id ned:

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

     

5. Føj programmet til din kundes lejer.

   Du skal have din ansøgning godkendt i hver kundelejer, hvor du vil bruge den. Denne godkendelse er nødvendig, fordi dit program interagerer med Microsoft Defender for Endpoint program på vegne af din kunde.

   En brugerkonto med de relevante tilladelser til din kundes lejer skal vælge samtykkelinket og godkende dit program.

   Samtykkelinket er af formularen:

   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-000000000000 skal erstattes med dit program-id.

   Når du har valgt samtykkelinket, skal du logge på kundens lejer og derefter give samtykke til programmet.

   

   Derudover skal du bede din kunde om deres lejer-id og gemme det til fremtidig brug, når du henter tokenet.

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

Få et eksempel på et adgangstoken

Hvis du vil hente adgangstoken på vegne af din kunde, skal du bruge kundens lejer-id på følgende tokenkøb.

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

Brug af PowerShell

# That code gets the App Context Token and save it to a file named "Latest-token.txt" under the current directory
# Paste below your Tenant ID, App ID and App Secret (App key).

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

$resourceAppIdUri = 'https://api.securitycenter.microsoft.com'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
$authBody = [Ordered] @{
    resource = "$resourceAppIdUri"
    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
Out-File -FilePath "./Latest-token.txt" -InputObject $token
return $token

Brug af C#

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. Hvis du vil opgradere, skal du se overførselsvejledningen.

1. Opret et nyt konsolprogram.

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

3. Tilføj følgende ved hjælp af kode:

    using Microsoft.Identity.Client;
   

   Denne kode blev testet med NuGet Microsoft.Identity.Client.

4. Kopiér/indsæt følgende kode i programmet (glem ikke at opdatere de tre variabler: tenantId, appIdog 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 af Python

Se Hent token ved hjælp af Python.

Brug af krøller

Bemærk!

Følgende procedure formodes Curl til Windows er allerede installeret på din computer

1. Åbn et kommandovindue.

2. Angiv CLIENT_ID som dit Azure-program-id.

3. Angiv CLIENT_SECRET som din Azure-programhemmelighed.

4. Angiv TENANT_ID til Azure-lejer-id'et for den kunde, der vil bruge dit program til at få adgang til Microsoft Defender for Endpoint program.

5. 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, der ligner følgende kodestykke:

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

Valider tokenet

Bekræft, at du har modtaget et korrekt token.

1. Kopiér/indsæt det token, du får i det forrige trin, i JWT for at afkode det.

2. Bekræft, at du får et rollekrav med de relevante tilladelser.

   På følgende skærmbillede kan du se et afkodet token, der er hentet fra et program med flere tilladelser til at Microsoft Defender for Endpoint:

   

   Kravet "tid" er det lejer-id, som tokenet tilhører.

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

1. Vælg den API, du vil bruge. Du kan få flere oplysninger under Understøttede Microsoft Defender for Endpoint API'er.

2. Angiv Autorisationsheaderen i den Http-anmodning, du sender til Bearer {token} (ihændehaver er autorisationsskemaet). Udløbstidspunktet for tokenet er én time (du kan sende mere end én anmodning med det samme token).

   Her er et eksempel på, hvordan du sender 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å

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