Używanie interfejsów API Ochrona punktu końcowego w usłudze Microsoft Defender

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 Ochrona punktu końcowego w usłudze Microsoft Defender dla klientów rządowych USA.

Porada

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

• api-us.securitycenter.microsoft.com
• api-eu.securitycenter.microsoft.com
• api-uk.securitycenter.microsoft.com
• api-au.securitycenter.microsoft.com

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

Jeśli potrzebujesz dostępu programowego Ochrona punktu końcowego w usłudze Microsoft Defender bez użytkownika, zapoznaj się z artykułem Access Ochrona punktu końcowego w usłudze Microsoft Defender with application context (Dostęp Ochrona punktu końcowego w usłudze Microsoft Defender z kontekstem aplikacji).

Jeśli nie masz pewności, jakiego dostępu potrzebujesz, przeczytaj stronę Wprowadzenie.

Ochrona punktu końcowego w usłudze Microsoft Defender uwidacznia wiele swoich danych i akcji za pośrednictwem zestawu programowych interfejsów API. Te interfejsy API umożliwiają automatyzację przepływów roboczych i wprowadzanie innowacji w oparciu o Ochrona punktu końcowego w usłudze Microsoft Defender możliwości. 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:

• Twórca aplikacji Microsoft Entra
• Uzyskiwanie tokenu dostępu przy użyciu tej aplikacji
• Uzyskiwanie dostępu do interfejsu API usługi Defender for Endpoint przy użyciu tokenu

Na tej stronie wyjaśniono, jak utworzyć aplikację Microsoft Entra, uzyskać token dostępu do Ochrona punktu końcowego w usłudze Microsoft Defender i zweryfikować token.

Uwaga

Podczas uzyskiwania dostępu do interfejsu API Ochrona punktu końcowego w usłudze Microsoft Defender w imieniu użytkownika potrzebne są odpowiednie uprawnienia aplikacji i uprawnienia użytkownika. Jeśli nie znasz uprawnień użytkownika na Ochrona punktu końcowego w usłudze Microsoft Defender, zobacz Zarządzanie dostępem do portalu przy użyciu kontroli dostępu opartej na rolach.

Porada

Jeśli masz uprawnienia do wykonywania akcji w portalu, masz uprawnienia do wykonywania akcji w interfejsie API.

Twórca aplikacji

1. Zaloguj się na platformie Azure przy użyciu konta użytkownika z rolą administratora globalnego .

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

   

3. Po wyświetleniu strony Rejestrowanie aplikacji wprowadź informacje o rejestracji aplikacji:

   • Nazwa — wprowadź znaczącą nazwę aplikacji, która będzie wyświetlana użytkownikom aplikacji.

   • Obsługiwane typy kont — wybierz konta, które chcesz obsługiwać w aplikacji.

     
     

     Obsługiwane typy kont	Opis
     Konta tylko w tym katalogu organizacyjnym	Wybierz tę opcję, jeśli tworzysz aplikację biznesową (LOB). Ta opcja jest niedostępna, jeśli nie rejestrujesz aplikacji w katalogu. Ta opcja jest mapowana na Microsoft Entra tylko jedną dzierżawę. Jest to opcja domyślna, chyba że rejestrujesz aplikację poza katalogiem. W przypadkach, gdy aplikacja jest zarejestrowana poza katalogiem, ustawieniem domyślnym jest Microsoft Entra wielodostępnych i osobistych kont Microsoft.
     Konta w dowolnym katalogu organizacyjnym	Wybierz tę opcję, jeśli chcesz kierować dane do wszystkich klientów biznesowych i edukacyjnych. Ta opcja jest mapowana na wielodostępną obsługę tylko Microsoft Entra. Jeśli aplikacja została zarejestrowana jako pojedyncza dzierżawa tylko dla Microsoft Entra, możesz ją zaktualizować tak, aby była Microsoft Entra wielodostępna i z powrotem do jednej dzierżawy za pośrednictwem bloku Uwierzytelnianie.
     Konta w dowolnym katalogu organizacyjnym i osobistych kontach Microsoft	Wybierz tę opcję, aby kierować dane do najszerszego zestawu klientów. Ta opcja jest mapowana na Microsoft Entra wielodostępnych i osobistych kont Microsoft. Jeśli aplikacja została zarejestrowana jako Microsoft Entra wielodostępnych i osobistych kont Microsoft, nie można tego zmienić w interfejsie użytkownika. Zamiast tego należy użyć edytora manifestu aplikacji, aby zmienić obsługiwane typy kont.

   • Identyfikator URI przekierowania (opcjonalnie) — wybierz typ aplikacji, którą tworzysz, klienta internetowego lub publicznego (mobile & desktop), a następnie wprowadź identyfikator URI przekierowania (lub adres URL odpowiedzi) dla aplikacji.

     • W przypadku aplikacji internetowych podaj podstawowy adres URL aplikacji. Może to być na przykład http://localhost:31544 adres URL aplikacji internetowej działającej na komputerze lokalnym. Użytkownicy będą używać tego adresu URL do logowania się do aplikacji klienckiej sieci Web.

     • W przypadku publicznych aplikacji klienckich podaj identyfikator URI używany przez Tożsamość Microsoft Entra do zwracania odpowiedzi tokenu. Wprowadź wartość specyficzną dla aplikacji, taką jak myapp://auth.

     Aby wyświetlić konkretne przykłady aplikacji internetowych lub aplikacji natywnych, zapoznaj się z naszymi przewodnikami Szybki start.

     Po zakończeniu wybierz pozycję Zarejestruj.

4. Zezwalaj aplikacji na dostęp do Ochrona punktu końcowego w usłudze Microsoft Defender i przypisz jej uprawnienie "Odczyt alertów":

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

     Uwaga

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

     

   • Wybierz pozycję Uprawnienia delegowane>Alert.Przeczytaj> wybierz pozycję Dodaj uprawnienia.

     

   Ważna

   Wybierz odpowiednie uprawnienia. Alerty odczytu to tylko przykład.

   Przykład:

   • Aby uruchomić zaawansowane zapytania, wybierz pozycję Uruchom zaawansowane zapytania uprawnienie .

   • Aby wyizolować urządzenie, wybierz pozycję Izolowanie uprawnień maszyny .

   • Aby określić, które uprawnienia są potrzebne, zapoznaj się z sekcją Uprawnienia w interfejsie API, który chcesz wywołać.

   • Wybierz pozycję Udziel zgody.

     Uwaga

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

     

5. Zapisz identyfikator aplikacji i identyfikator dzierżawy.

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

   

Uzyskiwanie tokenu dostępu

Aby uzyskać więcej informacji na temat tokenów Microsoft Entra, zobacz samouczek Microsoft Entra.

Korzystanie z języka C#

• Skopiuj/wklej poniższą klasę w aplikacji.

• Użyj metody AcquireUserTokenAsync z identyfikatorem aplikacji, identyfikatorem dzierżawy, nazwą użytkownika i hasłem, aby uzyskać token.

  namespace WindowsDefenderATP
  {
      using System.Net.Http;
      using System.Text;
      using System.Threading.Tasks;
      using Newtonsoft.Json.Linq;
  
      public static class WindowsDefenderATPUtils
      {
          private const string Authority = "https://login.microsoftonline.com";
  
          private const string WdatpResourceId = "https://api.securitycenter.microsoft.com";
  
          public static async Task<string> AcquireUserTokenAsync(string username, string password, string appId, string tenantId)
          {
              using (var httpClient = new HttpClient())
              {
                  var urlEncodedBody = $"resource={WdatpResourceId}&client_id={appId}&grant_type=password&username={username}&password={password}";
  
                  var stringContent = new StringContent(urlEncodedBody, Encoding.UTF8, "application/x-www-form-urlencoded");
  
                  using (var response = await httpClient.PostAsync($"{Authority}/{tenantId}/oauth2/token", stringContent).ConfigureAwait(false))
                  {
                      response.EnsureSuccessStatusCode();
  
                      var json = await response.Content.ReadAsStringAsync().ConfigureAwait(false);
  
                      var jObject = JObject.Parse(json);
  
                      return jObject["access_token"].Value<string>();
                  }
              }
          }
      }
  }
  

Weryfikowanie tokenu

Sprawdź, czy masz prawidłowy token:

• Skopiuj/wklej do narzędzia JWT token uzyskany w poprzednim kroku, aby go odkodować.

• Sprawdź, czy otrzymasz oświadczenie "scp" z odpowiednimi uprawnieniami aplikacji.

• Na poniższym zrzucie ekranu widać dekodowany token uzyskany z aplikacji w samouczku:

  

Uzyskiwanie dostępu do interfejsu API Ochrona punktu końcowego w usłudze Microsoft Defender przy użyciu tokenu

• Wybierz interfejs API, którego chcesz użyć — obsługiwane Ochrona punktu końcowego w usłudze Microsoft Defender interfejsy API.

• Ustaw nagłówek autoryzacji w żądaniu HTTP wysyłanym do elementu "Bearer {token}" (element nośny jest schematem autoryzacji).

• Czas wygaśnięcia tokenu wynosi 1 godzinę (możesz wysłać więcej niż jedno żądanie z tym samym tokenem).

• 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ż

• interfejsy API Ochrona punktu końcowego w usłudze Microsoft Defender
• Dostęp Ochrona punktu końcowego w usłudze Microsoft Defender z kontekstem aplikacji

Porada

Chcesz dowiedzieć się więcej? Engage ze społecznością microsoft security w naszej społeczności technicznej: Ochrona punktu końcowego w usłudze Microsoft Defender Tech Community.