Skapa en app med partneråtkomst till Microsoft Defender XDR-API:er
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 uttryckligen definierad användare (till exempel om du skriver en bakgrundsapp eller daemon) läser du 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 program med flera klientorganisationer Microsoft Entra.
- 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.
Logga in på Azure.
Gå till Microsoft Entra ID>Appregistreringar>Ny registrering.
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.
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.
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.
Anteckning
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".
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.
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.
Registrera ditt program-ID och ditt klientorganisations-ID på en säker plats. De visas under Översikt på programsidan.
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 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 som administratör för användarens klientorganisation och beviljar medgivande för 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.
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.
# 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
Anteckning
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 rad:
using Microsoft.Identity.Client;
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;
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"]
Anteckning
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.
- Ö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 den användare som vill använda din app för att få åtkomst till Microsoft Defender XDR.
- 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"}
- Kopiera och klistra in token i JSON-webbtokens valideringswebbplats, JWT, för att avkoda den.
- 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.All
behörigheterna , Incidents.ReadWrite.All
och AdvancedHunting.Read.All
:
- 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.
- I http-begäran som du ska skicka anger du auktoriseringsrubriken till
"Bearer" <token>
, Ägaren är auktoriseringsschemat och token är din verifierade token. - 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();
- översikt över Microsoft Defender XDR API:er
- Få åtkomst till Microsoft Defender XDR-API:er
- Skapa ett "Hello världen"-program
- 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
Tips
Vill du veta mer? Interagera med Microsofts säkerhetscommunity i vår Tech Community: Microsoft Defender XDR Tech Community.