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

Gäller för:

• Microsoft Defender XDR

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.

   

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.

   

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.

   

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.

   

   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.

   

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.

   

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

   

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.

   

   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.

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#

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

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 :

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();

Relaterade artiklar

• översikt över Microsoft Defender XDR API:er
• Få åtkomst till Microsoft Defender XDR-API:er
• Skapa ett program för "Hello världen"
• Skapa en app för att få åtkomst till Microsoft Defender XDR utan en användare
• Skapa en app för att få åtkomst till Microsoft Defender XDR-API:er för en användares räkning
• Läs mer om API-gränser och licensiering
• Förstå felkoder
• Hantera hemligheter i dina serverappar med Azure Key Vault
• OAuth 2.0-auktorisering för användarinloggning och API-åtkomst