Dela via

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

  • Artikel

Gäller för:

  • Microsoft Defender XDR

Viktigt

En del information gäller förinstallerad produkt som kan ha ändrats mycket innan den släpps kommersiellt. Microsoft lämnar inga garantier, uttryckliga eller underförstådda, med avseende på den information som anges här.

Den här sidan beskriver hur du skapar ett program för att få programmatisk åtkomst till Microsoft Defender XDR utan en definierad användare, till exempel om du skapar en daemon- eller bakgrundstjänst.

Om du behöver programmatisk åtkomst till Microsoft Defender XDR för en eller flera användares räkning kan du läsa Skapa en app för att få åtkomst till Microsoft Defender XDR API:er för en användares räkning och Skapa en app med partneråtkomst till Microsoft Defender XDR API:er. Om du inte är säker på vilken typ av åtkomst du behöver kan du läsa Kom igång.

Microsoft Defender XDR 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 använda Microsoft Defender XDR funktioner. Den här 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 dessa API:er:

  • Skapa ett Microsoft Entra program.
  • Hämta en åtkomsttoken med det här programmet.
  • Använd token för att komma åt Microsoft Defender XDR API.

Den här artikeln beskriver hur du:

  • Skapa ett Microsoft Entra program
  • Hämta en åtkomsttoken till Microsoft Defender XDR
  • Verifiera token.

Skapa en app

  1. Logga in på Azure som en användare med rollen Global administratör .

  2. Gå till Microsoft Entra ID>Appregistreringar>Ny registrering.

    Fliken Ny registrering i Microsoft Defender-portalen

  3. I formuläret väljer du ett namn för ditt program och väljer sedan Registrera.

  4. På programsidan väljer du API-behörigheter>Lägg till behörighets-API>:er som min organisation använder>, skriver Microsoft Threat Protection och väljer Microsoft Threat Protection. Din app kan nu komma åt Microsoft Defender XDR.

    Tips

    Microsoft Threat Protection är ett tidigare namn för Microsoft Defender XDR och visas inte i den ursprungliga listan. Du måste börja skriva dess namn i textrutan för att se det visas.

    Användningsfliken för organisationens API:er i Microsoft Defender-portalen

  5. Välj Programbehörigheter. Välj relevanta behörigheter för ditt scenario (till exempel Incident.Read.All) och välj sedan Lägg till behörigheter.

    Programbehörighetsfönstret i Microsoft Defender-portalen

    Obs!

    Du måste välja relevanta behörigheter för ditt scenario. Läs alla incidenter är bara ett exempel. Om du vill ta reda på vilken behörighet du behöver kan du titta på avsnittet Behörigheter i det API som du vill anropa.

    Om du till exempel 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".

  6. Välj Bevilja administratörsmedgivande. Varje gång du lägger till en behörighet måste du välja Bevilja administratörsmedgivande för att den ska börja gälla.

    Fönstret med beviljande av medgivande i Microsoft Defender-portalen

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

    Tips

    När du har valt Lägg till väljer du kopiera det genererade hemlighetsvärdet. Du kommer inte att kunna hämta det hemliga värdet när du har lämnat.

    Fönstret Skapa app i Microsoft Defender-portalen

  8. Registrera ditt program-ID och ditt klientorganisations-ID på en säker plats. De visas under Översikt på programsidan.

    Fönstret Översikt i Microsoft Defender-portalen

  9. Endast för Microsoft Defender XDR partner: Följ de här anvisningarna för partneråtkomst via Microsoft Defender XDR-API:er, ange att din app ska vara flera klientorganisationer så att den kan vara tillgänglig i alla klienter när du har fått administratörsmedgivande. Partneråtkomst 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 klientorganisationer. Det krävs inte om du skapar en tjänst som du bara vill köra i din klientorganisation, till exempel 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.

    Eftersom ditt program interagerar med Microsoft Defender XDR för dina användares räkning måste det godkännas för varje klient som du tänker använda den på.

    Den globala Active Directory-administratören för varje klientorganisation måste välja medgivandelänken och godkänna din app.

    Medgivandelänken har följande struktur:

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

    Siffrorna 00000000-0000-0000-0000-000000000000 bör ersättas 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.

Viktigt

Även om exemplen i det här avsnittet uppmuntrar dig att klistra in hemliga värden i testsyfte bör du aldrig hårdkoda hemligheter i ett program som körs i produktion. En tredje part kan använda din hemlighet för att komma åt resurser. Du kan skydda appens hemligheter med hjälp av Azure Key Vault. Ett praktiskt exempel på hur du kan skydda din app finns i Hantera hemligheter i dina serverappar med Azure Key Vault.

Hämta en åtkomsttoken med PowerShell

# This code gets the application context token and saves it to a file named "Latest-token.txt" under the current directory.

$tenantId = '' # Paste your directory (tenant) ID here
$clientId = '' # Paste your application (client) ID here
$appSecret = '' # Paste your own app secret here to test, then store it in a safe place, such as the Azure Key Vault!

$resourceAppIdUri = 'https://api.security.microsoft.com'
$oAuthUri = "https://login.windows.net/$tenantId/oauth2/token"

$authBody = [Ordered] @{
    resource = $resourceAppIdUri
    client_id = $clientId
    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

Hämta en åtkomsttoken med C#

Obs!

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 .

  1. Skapa ett nytt konsolprogram.

  2. Installera NuGet Microsoft.Identity.Client.

  3. Lägg till följande rad:

    using Microsoft.Identity.Client;

  4. Kopiera och klistra in följande kod i din app (glöm inte att uppdatera de tre variablerna: tenantId, clientId, appSecret):

    csharp
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;

Hämta en åtkomsttoken med Hjälp av Python

import json
import urllib.request
import urllib.parse

tenantId = '' # Paste your directory (tenant) ID here
clientId = '' # Paste your application (client) ID here
appSecret = '' # Paste your own app secret here to test, then store it in a safe place, such as the Azure Key Vault!

url = "https://login.windows.net/%s/oauth2/token" % (tenantId)

resourceAppIdUri = 'https://api.security.microsoft.com'

body = {
    'resource' : resourceAppIdUri,
    'client_id' : clientId,
    'client_secret' : appSecret,
    'grant_type' : 'client_credentials'
}

data = urllib.parse.urlencode(body).encode("utf-8")

req = urllib.request.Request(url, data)
response = urllib.request.urlopen(req)
jsonResponse = json.loads(response.read())
aadToken = jsonResponse["access_token"]

Hämta en åtkomsttoken med curl

Obs!

Curl är förinstallerat på Windows 10, version 1803 och senare. För andra versioner av Windows laddar du ned och installerar verktyget direkt från den officiella curl-webbplatsen.

  1. Öppna en kommandotolk och ange CLIENT_ID till ditt Azure-program-ID.

  2. Ange CLIENT_SECRET till din Azure-programhemlighet.

  3. Ange TENANT_ID till Azure-klientorganisations-ID för kunden som vill använda din app för att få åtkomst till Microsoft Defender XDR.

  4. 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://api.security.microsoft.com/.default" -d "client_secret=%CLIENT_SECRET%" "https://login.microsoftonline.com/%TENANT_ID%/oauth2/v2.0/token" -k

    Ett lyckat svar ser ut så här:

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

Verifiera token

  1. Kopiera och klistra in token i JSON-webbtokens valideringswebbplats, JWT, för att avkoda den.

  2. Kontrollera att rollanspråket i den avkodade token innehåller önskade behörigheter.

    I följande bild kan du se en avkodad token som hämtats från en app med Incidents.Read.Allbehörigheterna , Incidents.ReadWrite.Alloch AdvancedHunting.Read.All :

    Fönstret Avkodad token i Microsoft Defender-portalen

Använda token för att komma åt Microsoft Defender XDR-API:et

  1. Välj det API som du vill använda (incidenter eller avancerad jakt). Mer information finns i Api:er för Microsoft Defender XDR som stöds.

  2. I http-begäran som du ska skicka ställer du in auktoriseringshuvudet på "Bearer" <token>, Ägaren är auktoriseringsschemat och token är din verifierade token.

  3. Token upphör att gälla inom en timme. Du kan skicka fler än en begäran under den här tiden med samma token.

I följande exempel visas hur du skickar en begäran för att hämta en lista över incidenter med hjälp av C#.

    var httpClient = new HttpClient();
    var request = new HttpRequestMessage(HttpMethod.Get, "https://api.security.microsoft.com/api/incidents");

    request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

    var response = httpClient.SendAsync(request).GetAwaiter().GetResult();

Tips

Vill du veta mer? Engage med Microsofts säkerhetscommunity i vår Tech Community: Microsoft Defender XDR Tech Community.