Dostęp partnerów za pośrednictwem 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 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:

• 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 Ochrona punktu końcowego w usłudze Microsoft Defender w imieniu klientów.

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 ułatwiają automatyzowanie 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:

1. Utwórz aplikację Microsoft Entra z wieloma dzierżawami.

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 Ochrona punktu końcowego w usłudze Microsoft Defender.

W poniższych krokach przedstawiono sposób tworzenia aplikacji Microsoft Entra, uzyskiwania tokenu dostępu do Ochrona punktu końcowego w usłudze Microsoft Defender 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.

2. Przejdź do Tożsamość Microsoft Entra>Rejestracje aplikacji>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 Ochrona punktu końcowego w usłudze Microsoft Defender 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ą Ochrona punktu końcowego w usłudze Microsoft Defender w imieniu klienta.

   Konto użytkownika z odpowiednimi uprawnieniami dla 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ę do dzierżawy klienta, a następnie udziel zgody aplikacji.

   

   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 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 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 Ochrona punktu końcowego w usłudze Microsoft Defender aplikacji.

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 Ochrona punktu końcowego w usłudze Microsoft Defender:

   

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

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

1. Wybierz interfejs API, którego chcesz użyć. Aby uzyskać więcej informacji, zobacz Obsługiwane interfejsy API Ochrona punktu końcowego w usłudze Microsoft Defender.

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
• Dostęp Ochrona punktu końcowego w usłudze Microsoft Defender w imieniu użytkownika

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.