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

  1. Zaloguj się do platformy Azure jako użytkownik z rolą administratora globalnego .

  2. Przejdź do Azure Active Directory > App-registraties > Nowa rejestracja.

    Karta Nowa rejestracja w portalu Microsoft 365 Defender

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

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

    Karta Użycia interfejsów API organizacji w portalu Microsoft 365 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 365 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 365 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 365 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 365 Defender

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

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

  2. Zainstaluj 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 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 365 Defender.

  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 365 Defender

Uzyskiwanie dostępu do interfejsu API Microsoft 365 Defender 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 365 Defender.

  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();