Skapa en app för att få åtkomst till Microsoft Defender för Endpoint utan en användare

Artikel
05/03/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

Den här sidan beskriver hur du skapar ett program för att få programmatisk åtkomst till Defender för Endpoint utan en användare. Om du behöver programmatisk åtkomst till Defender för Endpoint för en användares räkning kan du läsa Hämta åtkomst med användarkontext. Om du inte är säker på vilken åtkomst du behöver kan du läsa Kom igång.

Microsoft Defender för Endpoint exponerar mycket av sina data och åtgärder via en uppsättning programmatiska API:er. Dessa API:er hjälper dig att automatisera arbetsflöden och innovationer baserat på Funktionerna i Defender för Endpoint. 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änd token för att komma åt Defender för Endpoint API.

Den här artikeln beskriver hur du skapar ett Microsoft Entra program, hämtar en åtkomsttoken för att Microsoft Defender för Endpoint och validerar token.

Skapa en app

Logga in på Azure med en användare som har rollen Global administratör .
Gå till Microsoft Entra ID>Appregistreringar>Ny registrering.
I registreringsformuläret väljer du ett namn för ditt program och väljer sedan Registrera.
Om du vill att din app ska få åtkomst till Defender för Endpoint och tilldela den behörigheten Läs alla aviseringar väljer du API-behörigheter>Lägg till behörighets-API>:er som min organisation använder>, skriver WindowsDefenderATP och väljer sedan WindowsDefenderATP.

Obs!

WindowsDefenderATP visas inte i den ursprungliga listan. Börja skriva dess namn i textrutan för att se det visas.

Välj Programbehörigheter>Alert.Read.All och välj sedan Lägg till behörigheter.

Du måste välja relevanta behörigheter. "Läs alla aviseringar" är bara ett exempel. Till exempel:
- Om du vill köra avancerade frågor väljer du behörigheten Kör avancerade frågor.
- Om du vill isolera en enhet väljer du behörigheten "Isolera dator".
- Om du vill ta reda på vilken behörighet du behöver kan du titta i avsnittet Behörigheter i api:et som du är intresserad av att anropa.
Välj Bevilja medgivande.

Obs!

Varje gång du lägger till en behörighet måste du välja Bevilja medgivande för att den nya behörigheten ska börja gälla.
Om du vill lägga till en hemlighet i programmet väljer du Certifikat & hemligheter, lägger till en beskrivning i hemligheten och väljer sedan Lägg till.

Obs!

När du har valt Lägg till väljer du kopiera det genererade hemlighetsvärdet. Du kan inte hämta det här värdet när du har lämnat.
Skriv ned ditt program-ID och ditt klientorganisations-ID. På programsidan går du till Översikt och kopierar följande.
Endast för Microsoft Defender för Endpoint partner. Ange att din app ska ha flera klientorganisationer (tillgängligt i alla klienter efter medgivande). Detta krävs för appar från tredje part (till exempel om du skapar en app som är avsedd att köras i flera kunders klientorganisation). Detta krävs inte om du skapar en tjänst som du bara vill köra i din klientorganisation (till exempel om du skapar ett program för din egen användning som bara interagerar med dina egna data). Så här ställer du in appen på flera klientorganisationer:
- Gå till Autentisering och lägg till https://portal.azure.com som omdirigerings-URI.
- Längst ned på sidan, under Kontotyper som stöds, väljer du Konton i alla organisationskatalogprogramsmedgivande för din app för flera klientorganisationer.
Du behöver ditt program för att godkännas i varje klientorganisation där du tänker använda det. Det beror på att ditt program interagerar med Defender för Endpoint för din kunds räkning.

Du (eller din kund om du skriver en app från tredje part) måste välja medgivandelänken och godkänna din app. Medgivandet ska göras med en användare som har administratörsbehörighet i Active Directory.

Medgivandelänken skapas på följande sätt:
```
https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true
```
Där 000000000-0000-0000-0000-00000000000 ersätts med ditt program-ID.

Klart! Du har registrerat ett program! Se exempel nedan för tokenförvärv och validering.

Hämta en åtkomsttoken

Mer information om Microsoft Entra-token finns i självstudien om Microsoft Entra.

Använda 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

Använd C#:

Följande kod testades med NuGet Microsoft.Identity.Client 3.19.8.

Viktigt

NuGet-paketet Microsoft.IdentityModel.Clients.ActiveDirectory och Azure AD Authentication Library (ADAL) har blivit inaktuella. Inga nya funktioner har lagts till sedan den 30 juni 2020. Vi rekommenderar starkt att du uppgraderar. Mer information finns i migreringsguiden .

Skapa ett nytt konsolprogram.
Installera NuGet Microsoft.Identity.Client.
Lägg till följande:
```
using Microsoft.Identity.Client;
```

Kopiera och klistra in följande kod i din app (glöm inte att uppdatera de tre variablerna: 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;

Använda Python

Se Hämta token med Python.

Använda Curl

Obs!

Följande procedur förutsätter att Curl för Windows redan är installerat på datorn.

Öppna en kommandotolk och ange CLIENT_ID till ditt Azure-program-ID.
Ange CLIENT_SECRET till din Azure-programhemlighet.
Ange TENANT_ID till Azure-klientorganisations-ID för kunden som vill använda din app för att få åtkomst till Defender för Endpoint.

Kör följande 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 ett svar i följande form:

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

Verifiera token

Kontrollera att du har rätt token:

Kopiera och klistra in den token som du fick i föregående steg i JWT för att avkoda den.
Kontrollera att du får ett rollanspråk med önskade behörigheter.

I följande bild kan du se en avkodad token som hämtats från en app med behörighet till alla Microsoft Defender för Endpoint roller:

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

Välj det API som du vill använda. Mer information finns i Defender för Endpoint-API:er som stöds.
Ange auktoriseringshuvudet i http-begäran som du skickar till "Bearer {token}" (Ägarna är auktoriseringsschemat).
Förfallotiden för token är en timme. Du kan skicka fler än en begäran med samma token.

Följande är ett 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