Tworzenie aplikacji z dostępem partnera do interfejsów API Microsoft Defender XDR

Artykuł
11/19/2024

Dotyczy:

Microsoft Defender XDR

Ważna

Niektóre informacje odnoszą się do wstępnie wydanego produktu, który może zostać znacząco zmodyfikowany przed jego komercyjną premierą. Firma Microsoft nie udziela żadnych gwarancji, wyraźnych ani dorozumianych, w odniesieniu do podanych tutaj informacji.

Na tej stronie opisano sposób tworzenia aplikacji Microsoft Entra, która ma programowy dostęp do Microsoft Defender XDR w imieniu użytkowników w wielu dzierżawach. Aplikacje wielodostępne są przydatne do obsługi dużych grup użytkowników.

Jeśli potrzebujesz dostępu programowego do Microsoft Defender XDR w imieniu jednego użytkownika, zobacz Tworzenie aplikacji w celu uzyskania dostępu do interfejsów API Microsoft Defender XDR w imieniu użytkownika. Jeśli potrzebujesz dostępu bez jawnie zdefiniowanego użytkownika (na przykład w przypadku pisania aplikacji w tle lub demona), zobacz Tworzenie aplikacji w celu uzyskania dostępu do Microsoft Defender XDR bez użytkownika. Jeśli nie masz pewności, jakiego rodzaju dostępu potrzebujesz, zobacz Wprowadzenie.

Microsoft Defender XDR uwidacznia wiele swoich danych i akcji za pośrednictwem zestawu programowych interfejsów API. Te interfejsy API ułatwiają automatyzowanie przepływów pracy i korzystanie z możliwości Microsoft Defender XDR. Ten dostęp do interfejsu API wymaga uwierzytelniania OAuth2.0. Aby uzyskać więcej informacji, zobacz Przepływ kodu autoryzacji OAuth 2.0.

Ogólnie rzecz biorąc, należy wykonać następujące kroki, aby użyć tych interfejsów API:

Utwórz aplikację Microsoft Entra.
Pobierz token dostępu przy użyciu tej aplikacji.
Użyj tokenu, aby uzyskać dostęp do interfejsu API Microsoft Defender XDR.

Ponieważ ta aplikacja jest wielodostępna, musisz również wyrazić zgodę administratora od każdej dzierżawy w imieniu jej użytkowników.

W tym artykule wyjaśniono, jak:

Tworzenie aplikacji Microsoft Entra z wieloma dzierżawami
Uzyskaj autoryzowaną zgodę administratora użytkownika dla aplikacji, aby uzyskać dostęp do Microsoft Defender XDR potrzebnych zasobów.
Uzyskiwanie tokenu dostępu do Microsoft Defender XDR
Weryfikowanie tokenu

Microsoft Defender XDR uwidacznia wiele swoich danych i akcji za pośrednictwem zestawu programowych interfejsów API. Te interfejsy API pomogą Ci zautomatyzować przepływy robocze i wprowadzać innowacje w oparciu o Microsoft Defender XDR możliwości. Dostęp do interfejsu API wymaga uwierzytelniania OAuth2.0. Aby uzyskać więcej informacji, zobacz Przepływ kodu autoryzacji OAuth 2.0.

Ogólnie rzecz biorąc, należy wykonać następujące kroki, aby korzystać z interfejsów API:

Tworzenie aplikacji Microsoft Entra wielodostępnej.
Uzyskaj autoryzację (zgodę) administratora użytkownika, aby aplikacja uzyskiwała dostęp do Microsoft Defender XDR potrzebnych zasobów.
Pobierz token dostępu przy użyciu tej aplikacji.
Użyj tokenu, aby uzyskać dostęp do interfejsu API Microsoft Defender XDR.

W poniższych krokach przedstawiono sposób tworzenia aplikacji Microsoft Entra wielodostępnej, uzyskiwania tokenu dostępu do Microsoft Defender XDR i weryfikowania tokenu.

Tworzenie aplikacji wielodostępnej

Zaloguj się do platformy Azure.
Przejdź do Tożsamość Microsoft Entra>Rejestracje aplikacji>Nowa rejestracja.
W formularzu rejestracji:
- Wybierz nazwę aplikacji.
- W obszarze Obsługiwane typy kont wybierz pozycję Konta w dowolnym katalogu organizacyjnym (dowolny katalog Microsoft Entra) — wielodostępny.
- Wypełnij sekcję Identyfikator URI przekierowania . Wybierz pozycję Wpisz Sieć Web i podaj identyfikator URI przekierowania jako https://portal.azure.com.
Po zakończeniu wypełniania formularza wybierz pozycję Zarejestruj.
Na stronie aplikacji wybierz pozycję Uprawnienia interfejsu APIDodaj interfejsy> API uprawnień > używane przez >moją organizację, wpisz Microsoft Threat Protection i wybierz pozycję Microsoft Threat Protection. Aplikacja może teraz uzyskiwać dostęp do Microsoft Defender XDR.

Porada

Usługa Microsoft Threat Protection jest poprzednią nazwą Microsoft Defender XDR i nie będzie wyświetlana na oryginalnej liście. Aby je wyświetlić, musisz zacząć pisać jego nazwę w polu tekstowym.
Wybierz pozycję Uprawnienia aplikacji. Wybierz odpowiednie uprawnienia dla danego scenariusza (na przykład Incident.Read.All), a następnie wybierz pozycję Dodaj uprawnienia.

Uwaga

Musisz wybrać odpowiednie uprawnienia dla danego scenariusza. Przeczytaj, że wszystkie zdarzenia to tylko przykład. Aby określić, którego uprawnienia potrzebujesz, zapoznaj się z sekcją Uprawnienia w interfejsie API, który chcesz wywołać.

Aby na przykład uruchamiać zaawansowane zapytania, wybierz uprawnienie "Uruchamianie zaawansowanych zapytań". Aby wyizolować urządzenie, wybierz uprawnienie "Izolowanie maszyny".
Wybierz pozycję Udziel zgody administratora. Za każdym razem, gdy dodasz uprawnienie, musisz wybrać opcję Udziel zgody administratora , aby ta zgoda weszła w życie.
Aby dodać wpis tajny do aplikacji, wybierz pozycję Certyfikaty & wpisów tajnych, dodaj opis do wpisu tajnego, a następnie wybierz pozycję Dodaj.

Porada

Po wybraniu pozycji Dodaj wybierz pozycję Skopiuj wygenerowaną wartość wpisu tajnego. Nie będzie można pobrać wartości wpisu tajnego po opuszczeniu.
Zarejestruj identyfikator aplikacji i identyfikator dzierżawy w bezpiecznym miejscu. Są one wyświetlane w obszarze Przegląd na stronie aplikacji.
Dodaj aplikację do dzierżawy użytkownika.

Ponieważ aplikacja współdziała z Microsoft Defender XDR w imieniu użytkowników, musi zostać zatwierdzona dla każdej dzierżawy, w której zamierzasz z niej korzystać.

Administrator z dzierżawy użytkownika musi wyświetlić link zgody i zatwierdzić aplikację.

Link zgody ma następujący formularz:
```
https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true
```
Cyfry 00000000-0000-0000-0000-000000000000 powinny zostać zastąpione identyfikatorem aplikacji.

Po kliknięciu linku zgody zaloguj się jako administrator dzierżawy użytkownika i udzielij zgody dla aplikacji.

Musisz również poprosić użytkownika o identyfikator dzierżawy. Identyfikator dzierżawy jest jednym z identyfikatorów używanych do uzyskiwania tokenów dostępu.

Ukończono! Aplikacja została pomyślnie zarejestrowana!
Zapoznaj się z poniższymi przykładami dotyczącymi uzyskiwania i walidacji tokenu.

Uzyskiwanie tokenu dostępu

Aby uzyskać więcej informacji na temat tokenów Microsoft Entra, zobacz samouczek Microsoft Entra.

Ważna

Chociaż przykłady w tej sekcji zachęcają do wklejania wartości wpisów tajnych do celów testowych, nigdy nie należy kodować wpisów tajnych do aplikacji działającej w środowisku produkcyjnym. Inna firma może użyć Twojego wpisu tajnego do uzyskania dostępu do zasobów. Możesz pomóc w zabezpieczeniu wpisów tajnych aplikacji przy użyciu usługi Azure Key Vault. Praktyczny przykład sposobu ochrony aplikacji można znaleźć w temacie Zarządzanie wpisami tajnymi w aplikacjach serwera przy użyciu usługi Azure Key Vault.

Porada

W poniższych przykładach użyj identyfikatora dzierżawy użytkownika, aby sprawdzić, czy skrypt działa.

Uzyskiwanie tokenu dostępu przy użyciu programu 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

Uzyskiwanie tokenu dostępu przy użyciu języka C#

Uwaga

Poniższy kod został przetestowany przy użyciu narzędzia Nuget Microsoft.Identity.Client 3.19.8.

Ważna

Pakiet NuGet Microsoft.IdentityModel.Clients.ActiveDirectory i biblioteka uwierzytelniania Azure AD (ADAL) zostały przestarzałe. Od 30 czerwca 2020 r. nie dodano żadnych nowych funkcji. Zdecydowanie zachęcamy do uaktualnienia. Aby uzyskać więcej informacji, zobacz przewodnik migracji .

Utwórz nową aplikację konsolową.
Zainstaluj plik NuGet Microsoft.Identity.Client.
Dodaj następujący wiersz:
```
using Microsoft.Identity.Client;
```

Skopiuj i wklej następujący kod do aplikacji (nie zapomnij zaktualizować trzech zmiennych: 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;

Uzyskiwanie tokenu dostępu przy użyciu języka 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"]

Uzyskiwanie tokenu dostępu przy użyciu narzędzia curl

Uwaga

Program Curl jest wstępnie instalowany w Windows 10, wersjach 1803 i nowszych. W przypadku innych wersji systemu Windows pobierz i zainstaluj narzędzie bezpośrednio z oficjalnej witryny internetowej curl.

Otwórz wiersz polecenia i ustaw CLIENT_ID na identyfikator aplikacji platformy Azure.
Ustaw CLIENT_SECRET na wpis tajny aplikacji platformy Azure.
Ustaw TENANT_ID na identyfikator dzierżawy platformy Azure użytkownika, który chce korzystać z aplikacji w celu uzyskania dostępu do Microsoft Defender XDR.
Uruchom następujące polecenie:

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

Pomyślna odpowiedź będzie wyglądać następująco:

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

Weryfikowanie tokenu

Skopiuj i wklej token do witryny internetowej modułu sprawdzania poprawności tokenu internetowego JSON JWT, aby go odkodować.
Upewnij się, że oświadczenia ról w ramach dekodowanego tokenu zawierają żądane uprawnienia.

Na poniższej ilustracji widać dekodowany token uzyskany z aplikacji z Incidents.Read.Alluprawnieniami , Incidents.ReadWrite.Alli :AdvancedHunting.Read.All

Uzyskiwanie dostępu do interfejsu API Microsoft Defender XDR przy użyciu tokenu

Wybierz interfejs API, którego chcesz użyć (zdarzenia lub zaawansowane wyszukiwanie zagrożeń). Aby uzyskać więcej informacji, zobacz Obsługiwane interfejsy API Microsoft Defender XDR.
W żądaniu http, które zamierzasz wysłać, ustaw nagłówek autoryzacji na "Bearer" <token>wartość , Element nośny jest schematem autoryzacji, a token jest zweryfikowanym tokenem.
Token wygaśnie w ciągu jednej godziny. W tym czasie możesz wysłać więcej niż jedno żądanie z tym samym tokenem.

W poniższym przykładzie pokazano, jak wysłać żądanie, aby uzyskać listę zdarzeń przy użyciu języka 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();

Porada

Chcesz dowiedzieć się więcej? Zaangażuj się w społeczność rozwiązań zabezpieczających firmy Microsoft w naszej społeczności technicznej Społeczność techniczna usługi Microsoft Defender XDR.

Udostępnij za pośrednictwem

Tworzenie aplikacji z dostępem partnera do interfejsów API Microsoft Defender XDR

Tworzenie aplikacji wielodostępnej

Uzyskiwanie tokenu dostępu

Uzyskiwanie tokenu dostępu przy użyciu programu PowerShell

Uzyskiwanie tokenu dostępu przy użyciu języka C#

Uzyskiwanie tokenu dostępu przy użyciu języka Python

Uzyskiwanie tokenu dostępu przy użyciu narzędzia curl

Weryfikowanie tokenu

Uzyskiwanie dostępu do interfejsu API Microsoft Defender XDR przy użyciu tokenu

Opinia

Dodatkowe zasoby

Udostępnij za pośrednictwem

Tworzenie aplikacji z dostępem partnera do interfejsów API Microsoft Defender XDR

Tworzenie aplikacji wielodostępnej

Uzyskiwanie tokenu dostępu

Uzyskiwanie tokenu dostępu przy użyciu programu PowerShell

Uzyskiwanie tokenu dostępu przy użyciu języka C#

Uzyskiwanie tokenu dostępu przy użyciu języka Python

Uzyskiwanie tokenu dostępu przy użyciu narzędzia curl

Weryfikowanie tokenu

Uzyskiwanie dostępu do interfejsu API Microsoft Defender XDR przy użyciu tokenu

Artykuły pokrewne

Opinia

Dodatkowe zasoby