Skapa en app med partneråtkomst till Microsoft Defender XDR API:er

  • 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 en Microsoft Entra app som har programmatisk åtkomst till Microsoft Defender XDR för användare i flera klientorganisationer. Appar för flera klientorganisationer är användbara för att betjäna stora grupper av användare.

Om du behöver programmatisk åtkomst till Microsoft Defender XDR för en enskild 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. Om du behöver åtkomst utan att en användare uttryckligen har definierats (till exempel om du skriver en bakgrundsapp eller daemon) kan du läsa Skapa en app för att få åtkomst till Microsoft Defender XDR utan en användare. 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.

Eftersom den här appen är för flera klientorganisationer behöver du även administratörsmedgivande från varje klient för användarnas räkning.

Den här artikeln beskriver hur du:

  • Skapa ett Microsoft Entra program för flera klientorganisationer
  • Få auktoriserat medgivande från användaradministratören för att ditt program ska få åtkomst till Microsoft Defender XDR de resurser som behövs.
  • Hämta en åtkomsttoken till Microsoft Defender XDR
  • Verifiera token

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 innovationer baserat på Microsoft Defender XDR funktioner. 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 för flera klientorganisationer.
  • Få auktoriserat (medgivande) av användaradministratören för att ditt program ska få åtkomst till Microsoft Defender XDR resurser som behövs.
  • Hämta en åtkomsttoken med det här programmet.
  • Använd token för att komma åt Microsoft Defender XDR API.

Följande steg med hjälper dig att skapa ett Microsoft Entra program för flera klientorganisationer, hämta en åtkomsttoken för att Microsoft Defender XDR och verifiera token.

Skapa appen för flera klientorganisationer

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

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

    Registreringsavsnittet för ett program i Microsoft Defender-portalen

  3. I registreringsformuläret:

    • Välj ett namn för ditt program.
    • Från Kontotyper som stöds väljer du Konton i valfri organisationskatalog (alla Microsoft Entra katalog) – flera klientorganisationer.
    • Fyll i avsnittet Omdirigerings-URI . Välj typ Webb och ge omdirigerings-URI:n som https://portal.azure.com.

    När du är klar med att fylla i formuläret väljer du Registrera.

    Registreringsavsnitt för ett program i Microsoft Defender-portalen

  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ändningsavsnittet för 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.

    Ett programs behörighetsfönster 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.

    Ett avsnitt för att bevilja administratörsmedgivande 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.

    Avsnittet Hemligt tillägg 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. Lägg till programmet i användarens klientorganisation.

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

    En global administratör från användarens klientorganisation måste visa medgivandelänken och godkänna ditt program.

    Medgivandelänken är i formuläret:

    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.

    När du har klickat på medgivandelänken loggar du in med den globala administratören för användarens klientorganisation och godkänner programmet.

    Programsidan för medgivande i Microsoft Defender-portalen

    Du måste också be användaren om deras klientorganisations-ID. Klientorganisations-ID:t är en av de identifierare som används för att hämta åtkomsttoken.

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

Tips

I följande exempel använder du en användares klientorganisations-ID för att testa att skriptet fungerar.

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!

$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):

    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 den användare 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://securitycenter.onmicrosoft.com/windowsatpservice/.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 anger du auktoriseringsrubriken till "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.