Dostęp partnerów za pośrednictwem interfejsów API usługi Microsoft Defender dla punktów końcowych

Dotyczy:

• Ochrona punktu końcowego w usłudze Microsoft Defender (plan 1)
• Ochrona punktu końcowego w usłudze Microsoft Defender (plan 2)
• Microsoft Defender dla Firm

Ważna

Zaawansowane możliwości wyszukiwania zagrożeń nie są uwzględniane w usłudze Defender dla firm.

Chcesz poznać usługę ochrony punktu końcowego w usłudze Microsoft Defender? Utwórz konto, aby skorzystać z bezpłatnej wersji próbnej.

Uwaga

Jeśli jesteś klientem rządowym USA, użyj identyfikatorów URI wymienionych w usłudze Microsoft Defender for Endpoint dla klientów rządowych USA.

Porada

Aby uzyskać lepszą wydajność, możesz użyć serwera bliżej lokalizacji geograficznej:

• us.api.security.microsoft.com
• eu.api.security.microsoft.com
• uk.api.security.microsoft.com
• au.api.security.microsoft.com
• swa.api.security.microsoft.com
• ina.api.security.microsoft.com

Na tej stronie opisano sposób tworzenia aplikacji Microsoft Entra w celu uzyskania dostępu programowego do usługi Microsoft Defender for Endpoint w imieniu klientów.

Usługa Microsoft Defender dla punktu końcowego uwidacznia wiele swoich danych i akcji za pośrednictwem zestawu programowych interfejsów API. Te interfejsy API ułatwiają automatyzowanie przepływów roboczych i wprowadzanie innowacji w oparciu o możliwości usługi Microsoft Defender for Endpoint. 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:

1. Tworzenie wielodostępnej aplikacji Microsoft Entra.

2. Uzyskaj autoryzację (zgodę) administratora klienta dla aplikacji, aby uzyskać dostęp do potrzebnych zasobów usługi Defender for Endpoint.

3. Pobierz token dostępu przy użyciu tej aplikacji.

4. Użyj tokenu, aby uzyskać dostęp do interfejsu API usługi Microsoft Defender for Endpoint.

W poniższych krokach przedstawiono sposób tworzenia aplikacji Microsoft Entra, uzyskiwania tokenu dostępu do usługi Microsoft Defender for Endpoint i weryfikowania tokenu.

Ważna

Firma Microsoft rekomenduje używanie ról z najmniejszą liczbą uprawnień. Pomaga to zwiększyć bezpieczeństwo organizacji. Administrator globalny to rola o wysokim poziomie uprawnień, która powinna być ograniczona do scenariuszy awaryjnych, gdy nie można użyć istniejącej roli.

Tworzenie aplikacji wielodostępnej

1. Zaloguj się do dzierżawy platformy Azure przy użyciu użytkownika z rolą administratora globalnego .

2. Przejdź do obszaruRejestracje> aplikacji Microsoft Entra ID>Nowa rejestracja.

   

3. W formularzu rejestracji:

   • Wybierz nazwę aplikacji.

   • Obsługiwane typy kont — konta w dowolnym katalogu organizacyjnym.

   • Identyfikator URI przekierowania — typ: Sieć Web, identyfikator URI: https://portal.azure.com

     

4. Zezwalaj aplikacji na dostęp do usługi Microsoft Defender for Endpoint i przypisz ją z minimalnym zestawem uprawnień wymaganych do ukończenia integracji.

   • Na stronie aplikacji wybierz pozycję Uprawnienia interfejsu API Dodaj interfejsy> APIuprawnień>,których moja organizacja używa> typu WindowsDefenderATP i wybierz pozycję WindowsDefenderATP.

   • WindowsDefenderATP nie jest wyświetlana na oryginalnej liście. Zacznij pisać jego nazwę w polu tekstowym, aby zobaczyć, jak jest wyświetlana.

     

Żądanie uprawnień interfejsu API

Aby określić, którego uprawnienia potrzebujesz, zapoznaj się z sekcją Uprawnienia w interfejsie API, który chcesz wywołać. Na przykład:

• Aby uruchomić zaawansowane zapytania, wybierz uprawnienie Uruchom zaawansowane zapytania .
• Aby wyizolować urządzenie, wybierz uprawnienie Izolowanie maszyny .

W poniższym przykładzie używamy uprawnienia Odczyt wszystkich alertów :

1. Wybierz pozycję Uprawnienia> aplikacjiAlert.Read.All> wybierz pozycję Dodaj uprawnienia

   

2. Wybierz pozycję Udziel zgody

   • Za każdym razem, gdy dodasz uprawnienie, musisz wybrać pozycję Udziel zgody , aby nowe uprawnienie weszło w życie.

   

3. Dodaj wpis tajny do aplikacji.

   • Wybierz pozycję Certyfikaty & wpisów tajnych, dodaj opis do wpisu tajnego i wybierz pozycję Dodaj.

   Po wybraniu pozycji Dodaj skopiuj wygenerowaną wartość wpisu tajnego. Nie będzie można pobrać go po opuszczeniu!

   

4. Zapisz identyfikator aplikacji:

   • Na stronie aplikacji przejdź do pozycji Przegląd i skopiuj następujące informacje:

     

5. Dodaj aplikację do dzierżawy klienta.

   Aplikacja musi zostać zatwierdzona w każdej dzierżawie klienta, w której zamierzasz jej używać. To zatwierdzenie jest konieczne, ponieważ aplikacja współdziała z aplikacją Microsoft Defender for Endpoint w imieniu klienta.

   Użytkownik z administratorem globalnym z dzierżawy klienta musi wybrać 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
   

   Gdzie 00000000-0000-0000-0000-000000000000 należy zastąpić identyfikator aplikacji.

   Po wybraniu linku zgody zaloguj się jako administrator globalny dzierżawy klienta i wyrazić zgodę na aplikację.

   

   Ponadto należy poprosić klienta o identyfikator dzierżawy i zapisać go do użycia w przyszłości podczas uzyskiwania tokenu.

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

Przykład uzyskiwania tokenu dostępu

Aby uzyskać token dostępu w imieniu klienta, użyj identyfikatora dzierżawy klienta w następujących przejęciach tokenu.

Aby uzyskać więcej informacji na temat tokenu Microsoft Entra, zobacz Samouczek dotyczący usługi Microsoft Entra.

Korzystanie z programu PowerShell

# That code gets the App Context Token and save it to a file named "Latest-token.txt" under the current directory
# Paste below your Tenant ID, App ID and App Secret (App key).

$tenantId = '' ### Paste your tenant ID here
$appId = '' ### Paste your Application ID here
$appSecret = '' ### Paste your Application key here

$resourceAppIdUri = 'https://api.securitycenter.microsoft.com'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
$authBody = [Ordered] @{
    resource = "$resourceAppIdUri"
    client_id = "$appId"
    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

Korzystanie z języka C#

Ważna

Pakiet NuGet Microsoft.IdentityModel.Clients.ActiveDirectory i Biblioteka uwierzytelniania usługi Azure AD (ADAL) zostały przestarzałe. Od 30 czerwca 2020 r. nie dodano żadnych nowych funkcji. Aby przeprowadzić uaktualnienie, zobacz przewodnik migracji.

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

2. Zainstaluj plik NuGet Microsoft.Identity.Client.

3. Dodaj następujący kod:

    using Microsoft.Identity.Client;
   

   Ten kod został przetestowany przy użyciu narzędzia NuGet Microsoft.Identity.Client.

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

Korzystanie z języka Python

Zobacz Pobieranie tokenu przy użyciu języka Python.

Korzystanie z narzędzia Curl

Uwaga

Poniższa procedura zakłada, że program Curl dla systemu Windows jest już zainstalowany na komputerze

1. Otwórz okno polecenia.

2. Ustaw CLIENT_ID na swój identyfikator aplikacji platformy Azure.

3. Ustaw CLIENT_SECRET na klucz tajny aplikacji platformy Azure.

4. Ustaw TENANT_ID na identyfikator dzierżawy platformy Azure klienta, który chce używać aplikacji do uzyskiwania dostępu do aplikacji usługi Microsoft Defender for Endpoint.

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

   Otrzymasz odpowiedź podobną do następującego fragmentu kodu:

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

Weryfikowanie tokenu

Potwierdź, że otrzymano prawidłowy token.

1. Skopiuj/wklej do JWT token pobrany w poprzednim kroku w celu jego dekodowania.

2. Potwierdź, że otrzymasz oświadczenie dotyczące ról z odpowiednimi uprawnieniami.

   Na poniższym zrzucie ekranu widać dekodowany token uzyskany z aplikacji z wieloma uprawnieniami do usługi Microsoft Defender for Endpoint:

   

   Oświadczenie "tid" jest identyfikatorem dzierżawy, do którego należy token.

Uzyskiwanie dostępu do interfejsu API usługi Microsoft Defender for Endpoint przy użyciu tokenu

1. Wybierz interfejs API, którego chcesz użyć. Aby uzyskać więcej informacji, zobacz Obsługiwane interfejsy API usługi Microsoft Defender for Endpoint.

2. Ustaw nagłówek Autoryzacja w wysyłanym Bearer {token} żądaniu HTTP (Element nośny jest schematem autoryzacji). Czas wygaśnięcia tokenu wynosi jedną godzinę (możesz wysłać więcej niż jedno żądanie z tym samym tokenem).

   Oto przykład wysyłania żądania uzyskania listy alertów przy użyciu języka C#:

   var httpClient = new HttpClient();
   
   var request = new HttpRequestMessage(HttpMethod.Get, "https://api.securitycenter.microsoft.com/api/alerts");
   
   request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
   
   var response = httpClient.SendAsync(request).GetAwaiter().GetResult();
   
    // Do something useful with the response
   

Zobacz też

• Obsługiwane interfejsy API usługi ochrony punktu końcowego w usłudze Microsoft Defender
• Uzyskiwanie dostępu do usługi Microsoft Defender dla punktu końcowego w imieniu użytkownika

Porada

Chcesz dowiedzieć się więcej? Skontaktuj się ze społecznością zabezpieczeń firmy Microsoft w naszej społeczności technicznej: Microsoft Defender for Endpoint Tech Community.