Tworzenie aplikacji w celu uzyskania dostępu do interfejsów API Microsoft Defender XDR w imieniu użytkownika

Dotyczy:

• Microsoft Defender XDR

Ważna

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 w imieniu jednego użytkownika.

Jeśli potrzebujesz dostępu programowego do Microsoft Defender XDR bez zdefiniowanego użytkownika (na przykład w przypadku pisania aplikacji w tle lub demona), zobacz Tworzenie aplikacji w celu uzyskania dostępu do Microsoft Defender XDR bez użytkownika. Jeśli chcesz zapewnić dostęp dla wielu dzierżaw — na przykład jeśli obsługujesz dużą organizację lub grupę klientów — zobacz 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
• Weryfikowanie tokenu

Uwaga

Podczas uzyskiwania dostępu do interfejsu API Microsoft Defender XDR w imieniu użytkownika potrzebne są odpowiednie uprawnienia aplikacji i uprawnienia użytkownika.

Porada

Jeśli masz uprawnienia do wykonywania akcji w portalu, masz uprawnienia do wykonywania akcji w interfejsie API. Aby uzyskać więcej informacji na temat ról i uprawnień, zobacz Zarządzanie dostępem do Microsoft Defender XDR przy użyciu Microsoft Entra ról globalnych.

Tworzenie aplikacji

1. Zaloguj się do platformy Azure.

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

   

3. W formularzu wybierz nazwę aplikacji i wprowadź następujące informacje dotyczące identyfikatora URI przekierowania, a następnie wybierz pozycję Zarejestruj.

   

   • Typ aplikacji: Klient publiczny
   • Identyfikator URI przekierowania:https://portal.azure.com

4. 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 delegowane. Wybierz odpowiednie uprawnienia dla danego scenariusza (na przykład Incident.Read), 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".

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

   

6. Zarejestruj identyfikator aplikacji i identyfikator dzierżawy w bezpiecznym miejscu. Są one wyświetlane w obszarze Przegląd na stronie aplikacji.

   

Uzyskiwanie tokenu dostępu

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

Uzyskiwanie tokenu dostępu w imieniu użytkownika przy użyciu programu PowerShell

Użyj biblioteki MSAL.PS, aby uzyskać tokeny dostępu z uprawnieniami delegowanymi. Uruchom następujące polecenia, aby uzyskać token dostępu w imieniu użytkownika:

Install-Module -Name MSAL.PS # Install the MSAL.PS module from PowerShell Gallery

$TenantId = " " # Paste your directory (tenant) ID here.
$AppClientId="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # Paste your application (client) ID here.

$MsalParams = @{
   ClientId = $AppClientId
   TenantId = $TenantId
   Scopes   = 'https://graph.microsoft.com/User.Read.All','https://graph.microsoft.com/Files.ReadWrite','https://api.securitycenter.windows.com/AdvancedQuery.Read'
}

$MsalResponse = Get-MsalToken @MsalParams
$AccessToken  = $MsalResponse.AccessToken
 
$AccessToken # Display the token in PS console

Weryfikowanie tokenu

1. Skopiuj i wklej token do narzędzia 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

Uzyskiwanie dostępu do interfejsu API Microsoft Defender XDR 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 Defender XDR.
2. W żądaniu http, które zamierzasz 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();

Artykuły pokrewne

• 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 Microsoft Defender XDR bez 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
• 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.