Dostęp partnerów za pośrednictwem interfejsów API Ochrona punktu końcowego w usłudze Microsoft Defender

Artykuł
05/03/2024

Dotyczy:

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:

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

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:

Twórca aplikacji Microsoft Entra z wieloma dzierżawami.
Uzyskaj autoryzację (zgodę) administratora klienta dla aplikacji, aby uzyskać dostęp do potrzebnych zasobów usługi Defender for Endpoint.
Pobierz token dostępu przy użyciu tej aplikacji.
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.

Twórca aplikacji wielodostępnej

Zaloguj się do dzierżawy platformy Azure przy użyciu użytkownika z rolą administratora globalnego .
Przejdź do Tożsamość Microsoft Entra>Rejestracje aplikacji>Nowa rejestracja.
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
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.
- Należy pamiętać, że system WindowsDefenderATP nie jest wyświetlany 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 uruchamiać zaawansowane zapytania, wybierz uprawnienie "Uruchamianie zapytań zaawansowanych"
Aby wyizolować urządzenie, wybierz uprawnienie "Izolowanie maszyny"

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

Wybierz pozycję Uprawnienia> aplikacjiAlert.Read.All> wybierz pozycję Dodaj uprawnienia
Wybierz pozycję Udziel zgody
- Uwaga: za każdym razem, gdy dodasz uprawnienie, musisz wybrać pozycję Udziel zgody , aby nowe uprawnienie weszło w życie.
Dodaj wpis tajny do aplikacji.
- Wybierz pozycję Certyfikaty & wpisów tajnych, dodaj opis do wpisu tajnego i wybierz pozycję Dodaj.
Ważne: Po wybraniu pozycji Dodaj skopiuj wygenerowaną wartość wpisu tajnego. Nie będzie można pobrać go po opuszczeniu!
Zapisz identyfikator aplikacji:
- Na stronie aplikacji przejdź do pozycji Przegląd i skopiuj następujące informacje:
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.

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ć identyfikatorem aplikacji

Po kliknięciu linku zgody zaloguj się za pomocą administratora globalnego 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.
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

Uwaga: 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#

Poniższy kod został przetestowany za pomocą narzędzia Nuget Microsoft.Identity.Client

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. Zdecydowanie zachęcamy do uaktualnienia. Aby uzyskać więcej informacji, zobacz przewodnik migracji .

Twórca nową aplikację konsolową
Instalowanie narzędzia NuGet Microsoft.Identity.Client
Dodaj poniższe elementy przy użyciu polecenia
```
using Microsoft.Identity.Client;
```

Skopiuj/wklej poniższy 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

Zapoznaj się z tematem Pobieranie tokenu przy użyciu języka Python.

Korzystanie z narzędzia Curl

Uwaga

Poniższa procedura ma curl dla systemu Windows jest już zainstalowany na komputerze

Otwórz okno polecenia.
Ustaw CLIENT_ID na identyfikator aplikacji platformy Azure.
Ustaw CLIENT_SECRET na wpis tajny aplikacji platformy Azure.
Ustaw TENANT_ID na identyfikator dzierżawy platformy Azure klienta, który chce używać aplikacji do uzyskiwania dostępu do aplikacji Ochrona punktu końcowego w usłudze Microsoft Defender.

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ź formularza:

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

Weryfikowanie tokenu

Potwierdź, że otrzymano prawidłowy token.

Skopiuj/wklej do JWT token pobrany w poprzednim kroku w celu jego dekodowania.
Potwierdź, że otrzymasz oświadczenie "role" z żądanymi 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

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.

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

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ż