Dostęp Microsoft Defender for Cloud Apps z kontekstem aplikacji

Artykuł
11/28/2024

Na tej stronie opisano sposób tworzenia aplikacji w celu uzyskania dostępu programowego do Defender for Cloud Apps bez użytkownika. Jeśli potrzebujesz dostępu programowego do Defender for Cloud Apps w imieniu użytkownika, zobacz Uzyskiwanie dostępu za pomocą kontekstu użytkownika. Jeśli nie masz pewności, jakiego dostępu potrzebujesz, zobacz stronę Zarządzanie tokenami interfejsu API .

Microsoft Defender for Cloud Apps 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 Defender for Cloud Apps 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:

Utwórz aplikację Microsoft Entra.
Pobierz token dostępu przy użyciu tej aplikacji.
Użyj tokenu, aby uzyskać dostęp do interfejsu API Defender for Cloud Apps.

W tym artykule wyjaśniono, jak utworzyć aplikację Microsoft Entra, uzyskać token dostępu do Microsoft Defender for Cloud Apps i zweryfikować token.

Tworzenie aplikacji dla Defender for Cloud Apps

W centrum administracyjne Microsoft Entra zarejestruj nową aplikację. Aby uzyskać więcej informacji, zobacz Szybki start: rejestrowanie aplikacji przy użyciu centrum administracyjne Microsoft Entra.
Aby umożliwić aplikacji dostęp do Defender for Cloud Apps i przypisać jej uprawnienie "Odczyt wszystkich alertów", na stronie aplikacji wybierz pozycję Uprawnienia interfejsu API Dodaj interfejsy> APIuprawnień>używane przez> moją organizację, wpisz microsoft Cloud App Security, a następnie wybierz pozycję Microsoft Cloud App Security.

Uwaga

Program Microsoft Cloud App Security nie jest wyświetlany na oryginalnej liście. Zacznij pisać jego nazwę w polu tekstowym, aby zobaczyć, jak jest wyświetlana. Pamiętaj, aby wpisać tę nazwę, mimo że produkt jest teraz nazywany Defender for Cloud Apps.
- Wybierz pozycję Uprawnienia> aplikacjiInvestigation.Read, a następnie wybierz pozycję Dodaj uprawnienia.
  
  Musisz wybrać odpowiednie uprawnienia. Investigation.Read to tylko przykład. Aby uzyskać inne zakresy uprawnień, zobacz Obsługiwane zakresy uprawnień
  - Aby określić, którego uprawnienia potrzebujesz, zapoznaj się z sekcją Uprawnienia w interfejsie API, który chcesz wywołać.
Wybierz pozycję Udziel zgody administratora.

Uwaga

Za każdym razem, gdy dodasz uprawnienie, musisz wybrać pozycję Udziel zgody administratora , aby nowe uprawnienie weszło w życie.
Aby dodać wpis tajny do aplikacji, wybierz pozycję Certyfikaty & wpisów tajnych, wybierz pozycję Nowy klucz tajny klienta, dodaj opis do wpisu tajnego, a następnie wybierz pozycję Dodaj.

Uwaga

Po wybraniu pozycji Dodaj wybierz pozycję Skopiuj wygenerowaną wartość wpisu tajnego. Nie będzie można pobrać tej wartości po opuszczeniu.
Zapisz identyfikator aplikacji i identyfikator dzierżawy. Na stronie aplikacji przejdź do pozycji Przegląd i skopiuj identyfikator aplikacji (klienta) i identyfikator katalogu (dzierżawy).
Tylko w przypadku partnerów Microsoft Defender for Cloud Apps. Ustaw aplikację na wielodostępną (dostępną we wszystkich dzierżawach po wyrażeniu zgody). Jest to wymagane w przypadku aplikacji innych firm (na przykład w przypadku utworzenia aplikacji, która ma być uruchamiana w dzierżawie wielu klientów). Nie jest to wymagane , jeśli utworzysz usługę, którą chcesz uruchomić tylko w dzierżawie (na przykład jeśli utworzysz aplikację dla własnego użycia, która będzie wchodzić w interakcje tylko z własnymi danymi). Aby ustawić aplikację jako wielodostępną:
- Przejdź do pozycji Uwierzytelnianie i dodaj https://portal.azure.com jako identyfikator URI przekierowania.
- W dolnej części strony w obszarze Obsługiwane typy kont wybierz pozycję Konta w dowolnej organizacji zgody aplikacji katalogu dla aplikacji wielodostępnej.
Aplikacja musi zostać zatwierdzona w każdej dzierżawie, w której ma być używana. Dzieje się tak, ponieważ aplikacja współdziała Defender for Cloud Apps w imieniu klienta.

Ty (lub twój klient, jeśli piszesz aplikację innej firmy) musisz wybrać link zgody i zatwierdzić aplikację. Zgodę należy wyrazić z użytkownikiem, który ma uprawnienia administracyjne w usłudze Active Directory.

Link zgody jest tworzony w następujący sposób:
```
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 jest zastępowany identyfikatorem aplikacji.

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

Obsługiwane zakresy uprawnień

Nazwa uprawnienia	Opis	Obsługiwane akcje
Investigation.read	Wykonaj wszystkie obsługiwane akcje dotyczące działań i alertów z wyjątkiem zamykania alertów. Wyświetl zakresy adresów IP, ale nie dodaj, nie zaktualizuj ani nie usuwaj. Wykonaj wszystkie akcje jednostek.	Lista działań, pobieranie, opinie Lista alertów, pobieranie, oznaczanie jako przeczytane/nieprzeczytane Lista jednostek, pobieranie, pobieranie drzewa Lista podsieci
Investigation.manage	Oprócz zarządzania alertami i zakresami adresów IP wykonaj wszystkie akcje investigation.read.	Lista działań, pobieranie, opinie Lista alertów, pobieranie, oznaczanie jako przeczytane/nieprzeczytane, zamykanie Lista jednostek, pobieranie, pobieranie drzewa Lista podsieci, tworzenie/aktualizowanie/usuwanie
Discovery.read	Wykonaj wszystkie obsługiwane akcje dotyczące działań i alertów z wyjątkiem zamykania alertów. Wyświetl listę raportów i kategorii odnajdywania.	Lista alertów, pobieranie, oznaczanie jako przeczytane/nieprzeczytane Raporty listy odnajdywania, kategorie raportów listy
Discovery.manage	Uprawnienia discovery.read Zamykanie alertów, przekazywanie plików odnajdywania i generowanie skryptów blokowych	Lista alertów, pobieranie, oznaczanie jako przeczytane/nieprzeczytane, zamykanie Raporty listy odnajdywania, kategorie raportów listy Przekazywanie pliku odnajdywania, generowanie skryptu bloku
Settings.read	Wyświetl listę zakresów adresów IP.	Lista podsieci
Settings.manage	Wyświetlanie listy zakresów adresów IP i zarządzanie nimi.	Lista podsieci, tworzenie/aktualizowanie/usuwanie

Uzyskiwanie tokenu dostępu

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

Korzystanie z programu PowerShell

# This script acquires the App Context Token and stores it in the variable $token for later use in the script.
# Paste your Tenant ID, App ID, and App Secret (App key) into the indicated quotes below.

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

$resourceAppIdUri = '05a65629-4c1b-48c1-a78b-804c4abdd4af'
$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

Korzystanie z języka C#

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

Utwórz nową aplikację konsolową.
Zainstaluj plik NuGet Microsoft.Identity.Client.
Dodaj następujące elementy:
```
using Microsoft.Identity.Client;
```

Skopiuj i wklej następujący kod w aplikacji (nie zapomnij zaktualizować trzech zmiennych: tenantId, appId, appSecret):

string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here
string appId = "00001111-aaaa-2222-bbbb-3333cccc4444"; // 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 = "05a65629-4c1b-48c1-a78b-804c4abdd4af";

IConfidentialClientApplication myApp = ConfidentialClientApplicationBuilder.Create(appId).WithClientSecret(appSecret).WithAuthority($"{authority}/{tenantId}").Build();

List scopes = new List() { $"{audience}/.default" };

AuthenticationResult authResult = myApp.AcquireTokenForClient(scopes).ExecuteAsync().GetAwaiter().GetResult();

string token = authResult.AccessToken;

Korzystanie z języka Python

Zobacz Biblioteka uwierzytelniania firmy Microsoft (MSAL) dla 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.

Otwórz wiersz polecenia i 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 korzystać z aplikacji w celu uzyskania dostępu do Defender for Cloud Apps.
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=05a65629-4c1b-48c1-a78b-804c4abdd4af/.default" -d "client_secret=%CLIENT_SECRET%" "https://login.microsoftonline.com/%TENANT_ID%/oauth2/v2.0/token" -k

Odpowiedź otrzymasz w następującym formularzu:

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

Weryfikowanie tokenu

Upewnij się, że masz prawidłowy token:

Skopiuj i wklej token uzyskany w poprzednim kroku do narzędzia JWT , aby go odkodować.
Sprawdź, czy otrzymasz oświadczenie "role" z żądanymi uprawnieniami
Na poniższej ilustracji widać dekodowany token uzyskany z aplikacji z uprawnieniami do wszystkich ról Microsoft Defender for Cloud Apps:

Zrzut ekranu przedstawiający weryfikację tokenu.

Uzyskiwanie dostępu do interfejsu API Microsoft Defender for Cloud Apps przy użyciu tokenu

Wybierz interfejs API, którego chcesz użyć. Aby uzyskać więcej informacji, zobacz Defender for Cloud Apps interfejsów 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 jedną godzinę. Możesz wysłać więcej niż jedno żądanie z tym samym tokenem.

Poniżej przedstawiono 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://portal.cloudappsecurity.com/cas/api/v1/alerts/");

    request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

    var response = httpClient.SendAsync(request).GetAwaiter().GetResult();

    // Do something useful with the response

Zobacz też

Zarządzanie tokenami interfejsu API

Udostępnij za pośrednictwem