Tworzenie aplikacji w celu uzyskania dostępu do Microsoft 365 Defender bez użytkownika
Uwaga
Chcesz skorzystać z usługi Microsoft 365 Defender? Dowiedz się więcej o tym, jak można oceniać i pilotować Microsoft 365 Defender.
Dotyczy:
- Microsoft 365 Defender
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 365 Defender bez zdefiniowanego użytkownika — na przykład w przypadku tworzenia demona lub usługi w tle.
Jeśli potrzebujesz dostępu programowego do Microsoft 365 Defender w imieniu co najmniej jednego użytkownika, zobacz Tworzenie aplikacji w celu uzyskania dostępu do interfejsów API Microsoft 365 Defender w imieniu użytkownika i Tworzenie aplikacji z dostępem partnera do interfejsów API Microsoft 365 Defender. Jeśli nie masz pewności, jakiego rodzaju dostępu potrzebujesz, zobacz Első lépések.
Microsoft 365 Defender 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 365 Defender. Ten dostęp do interfejsu API wymaga uwierzytelniania OAuth2.0. Aby uzyskać więcej informacji, zobacz Kod autoryzacji OAuth 2.0 Flow.
Ogólnie rzecz biorąc, należy wykonać następujące kroki, aby użyć tych interfejsów API:
- Utwórz aplikację Azure Active Directory (Azure AD).
- Pobierz token dostępu przy użyciu tej aplikacji.
- Użyj tokenu, aby uzyskać dostęp do interfejsu API Microsoft 365 Defender.
W tym artykule wyjaśniono, jak:
- Tworzenie aplikacji Azure AD
- Uzyskiwanie tokenu dostępu do Microsoft 365 Defender
- Zweryfikuj token.
Tworzenie aplikacji
Zaloguj się do platformy Azure jako użytkownik z rolą administratora globalnego .
Przejdź do Azure Active Directory > App-registraties > Nowa rejestracja.
W formularzu wybierz nazwę aplikacji, a następnie wybierz pozycję Zarejestruj.
Na stronie aplikacji wybierz pozycję Uprawnienia interfejsu API****Dodaj 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 365 Defender.
Porada
Usługa Microsoft Threat Protection jest poprzednią nazwą Microsoft 365 Defender 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 dla partnerów Microsoft 365 Defender: postępuj zgodnie z tymi instrukcjami dotyczącymi dostępu partnerów za pośrednictwem interfejsów API Microsoft 365 Defender, 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 365 Defender w imieniu użytkowników, musi zostać zatwierdzona dla każdej dzierżawy, w której zamierzasz z niej korzystać.
Administrator globalny 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 Azure Active Directory, zobacz samouczek Azure AD.
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 密钥保管库. Praktyczny przykład sposobu ochrony aplikacji można znaleźć w temacie Zarządzanie wpisami tajnymi w aplikacjach serwera przy użyciu usługi Azure 密钥保管库.
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żne
Pakiet microsoft.IdentityModel.Clients.ActiveDirectory NuGet 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 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;
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 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 365 Defender.
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
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
Uzyskiwanie dostępu do interfejsu API Microsoft 365 Defender 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 365 Defender.
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();
Powiązane artykuły:
- Omówienie interfejsów API Microsoft 365 Defender
- Uzyskiwanie dostępu do interfejsów API Microsoft 365 Defender
- Tworzenie aplikacji "Hello world"
- Tworzenie aplikacji w celu uzyskania dostępu do interfejsów API Microsoft 365 Defender w imieniu użytkownika
- Tworzenie aplikacji z dostępem partnerów z wieloma dzierżawami do interfejsów API Microsoft 365 Defender
- 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 密钥保管库
- Autoryzacja protokołu OAuth 2.0 na potrzeby logowania użytkownika i dostępu do interfejsu API