Udostępnij za pośrednictwem

Tworzenie aplikacji w celu uzyskania dostępu do Microsoft Defender XDR bez użytkownika

  • Artykuł

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 w celu uzyskania dostępu programowego do Microsoft Defender XDR bez zdefiniowanego użytkownika — na przykład w przypadku tworzenia demona lub usługi w tle.

Jeśli potrzebujesz dostępu programowego do Microsoft Defender XDR w imieniu co najmniej jednego użytkownika, zobacz Tworzenie aplikacji w celu uzyskania dostępu do interfejsów API Microsoft Defender XDR w imieniu użytkownika i Tworzenie aplikacji z dostępem partnera do interfejsów API Microsoft Defender XDR. 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.

W tym artykule wyjaśniono, jak:

  • Tworzenie aplikacji Microsoft Entra
  • Uzyskiwanie tokenu dostępu do Microsoft Defender XDR
  • Zweryfikuj token.

Tworzenie aplikacji

  1. Zaloguj się do platformy Azure.

  2. Przejdź do Tożsamość Microsoft Entra>Rejestracje aplikacji>Nowa rejestracja.

    Karta Nowa rejestracja w portalu Microsoft Defender

  3. W formularzu wybierz nazwę aplikacji, a następnie wybierz pozycję Zarejestruj.

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

    Karta Użycia interfejsów API organizacji w portalu Microsoft Defender

  5. Wybierz pozycję Uprawnienia aplikacji. Wybierz odpowiednie uprawnienia dla danego scenariusza (na przykład Incident.Read.All), a następnie wybierz pozycję Dodaj uprawnienia.

    Okienko uprawnień aplikacji w portalu Microsoft Defender

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

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

    Okienko dotyczące udzielania zgody w portalu Microsoft Defender

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

    Okienko tworzenia aplikacji w portalu Microsoft Defender

  8. Zarejestruj identyfikator aplikacji i identyfikator dzierżawy w bezpiecznym miejscu. Są one wyświetlane w obszarze Przegląd na stronie aplikacji.

    Okienko Przegląd w portalu Microsoft Defender

  9. Tylko w przypadku partnerów Microsoft Defender XDR: postępuj zgodnie z tymi instrukcjami dotyczącymi dostępu partnerów za pośrednictwem interfejsów API Microsoft Defender XDR, ustaw aplikację na wielodostępną, aby mogła być dostępna we wszystkich dzierżawach po uzyskaniu zgody administratora. Dostęp partnerów jest wymagany w przypadku aplikacji innych firm — na przykład w przypadku tworzenia aplikacji, która ma być uruchamiana w dzierżawach wielu klientów. Nie jest to wymagane , jeśli utworzysz usługę, którą chcesz uruchomić tylko w dzierżawie, na przykład aplikację dla własnego użycia, która będzie wchodzić w interakcje tylko z własnymi danymi. Aby ustawić aplikację na wielodostępną:

    • Przejdź do pozycji Uwierzytelnianie i dodaj https://portal.azure.com jako identyfikator URI przekierowania.

    • W dolnej części strony w obszarze Obsługiwane typy kont wybierz pozycję Konta w dowolnej zgody aplikacji katalogu organizacyjnego dla aplikacji wielodostępnej.

    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 usługi Active Directory dla każdej dzierżawy musi wybrać link zgody i zatwierdzić aplikację.

    Link zgody ma następującą strukturę:

    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.

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.

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

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 .

  1. Utwórz nową aplikację konsolową.

  2. Zainstaluj plik NuGet Microsoft.Identity.Client.

  3. Dodaj następujący wiersz:

    using Microsoft.Identity.Client;

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

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.

  1. Otwórz wiersz polecenia i ustaw CLIENT_ID na identyfikator aplikacji platformy Azure.

  2. Ustaw CLIENT_SECRET na wpis tajny aplikacji platformy Azure.

  3. Ustaw TENANT_ID na identyfikator dzierżawy platformy Azure klienta, który chce korzystać z aplikacji w celu uzyskania dostępu do Microsoft Defender XDR.

  4. 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://api.security.microsoft.com/.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

  1. Skopiuj i wklej token do witryny internetowej modułu sprawdzania poprawności tokenu internetowego JSON JWT, aby go odkodować.

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

    Okienko dekodowanego tokenu w portalu Microsoft Defender

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

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

  2. W żądaniu http, które chcesz wysłać, ustaw nagłówek autoryzacji na "Bearer" <token>wartość , element nośny jest schematem autoryzacji, a token jest zweryfikowanym tokenem.

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