Tworzenie aplikacji w celu uzyskania dostępu do Microsoft Defender XDR bez użytkownika
Dotyczy:
- Microsoft Defender XDR
Ważne
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.
Zaloguj się do platformy Azure.
Przejdź do Tożsamość Microsoft Entra>Rejestracje aplikacji>Nowa rejestracja.
W formularzu wybierz nazwę aplikacji, a następnie 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.
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.
Aby uzyskać więcej informacji na temat tokenów Microsoft Entra, zobacz samouczek Microsoft Entra.
Ważne
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.
# 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
Uwaga
Poniższy kod został przetestowany przy użyciu narzędzia Nuget Microsoft.Identity.Client 3.19.8.
Ważne
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
):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;
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"]
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 klienta, 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://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"}
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.All
uprawnieniami ,Incidents.ReadWrite.All
i :AdvancedHunting.Read.All
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 chcesz 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();
- Omówienie interfejsów API Microsoft Defender XDR
- Uzyskiwanie dostępu do interfejsów API Microsoft Defender XDR
- Tworzenie aplikacji "Hello world"
- Tworzenie aplikacji w celu uzyskania dostępu do interfejsów API Microsoft Defender XDR w imieniu użytkownika
- Tworzenie aplikacji z dostępem partnerów z wieloma dzierżawami do interfejsów API Microsoft Defender XDR
- Dowiedz się więcej o limitach interfejsu API i licencjonowaniu
- Omówienie kodów błędów
- Zarządzanie wpisami tajnymi w aplikacjach serwera przy użyciu usługi Azure Key Vault
- Autoryzacja protokołu OAuth 2.0 na potrzeby logowania użytkownika i dostępu do interfejsu API
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.