Uzyskiwanie dostępu do interfejsu API usługi Microsoft Defender dla Chmury Apps przy użyciu kontekstu użytkownika

Artykuł
08/19/2024

Na tej stronie opisano sposób tworzenia aplikacji w celu uzyskania programowego dostępu do aplikacji Defender dla Chmury w imieniu użytkownika.

Jeśli potrzebujesz dostępu programowego Microsoft Defender dla Chmury Apps bez użytkownika, zapoznaj się z tematem Access Microsoft Defender dla Chmury Apps with application context (Dostęp do aplikacji Microsoft Defender dla Chmury z kontekstem aplikacji).

Jeśli nie masz pewności, który dostęp jest potrzebny, przeczytaj stronę Wprowadzenie.

Microsoft Defender dla Chmury Apps udostępnia większość swoich danych i akcji za pomocą zestawu programowych interfejsów API. Te interfejsy API umożliwiają automatyzowanie przepływów pracy i wprowadzanie innowacji na podstawie możliwości Microsoft Defender dla Chmury Apps. 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ć interfejsów API:

Tworzenie aplikacji Firmy Microsoft Entra
Uzyskiwanie tokenu dostępu przy użyciu tej aplikacji
Uzyskiwanie dostępu do interfejsu API usługi Defender dla Chmury Apps przy użyciu tokenu

Na tej stronie wyjaśniono, jak utworzyć aplikację Firmy Microsoft Entra, uzyskać token dostępu do aplikacji Microsoft Defender dla Chmury i zweryfikować token.

Uwaga

Podczas uzyskiwania dostępu do interfejsu API usługi Microsoft Defender dla Chmury Apps w imieniu użytkownika potrzebne będzie odpowiednie uprawnienie aplikacji i uprawnienie użytkownika. Jeśli nie znasz uprawnień użytkownika w usłudze Microsoft Defender dla Chmury Apps, zobacz Zarządzanie dostępem administratora.

Napiwek

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

Utwórz aplikację

W centrum administracyjnym firmy Microsoft Entra zarejestruj nową aplikację. Aby uzyskać więcej informacji, zobacz Szybki start: rejestrowanie aplikacji w centrum administracyjnym firmy Microsoft Entra.

Gdy pojawi się strona Rejestrowanie aplikacji, wprowadź informacje rejestracyjne aplikacji:

Nazwa — wprowadź zrozumiałą nazwę aplikacji wyświetlaną użytkownikom aplikacji.

Obsługiwane typy konta — wybierz konta, które aplikacja ma obsługiwać.

Obsługiwane typy kont	Opis
Konta tylko w tym katalogu organizacyjnym	Wybierz tę opcję, jeśli kompilujesz aplikację biznesową. Ta opcja nie jest dostępna, jeśli nie rejestrujesz aplikacji w katalogu. Ta opcja mapuje na usługę Microsoft Entra-only single-tenant. Jest to opcja domyślna, chyba że rejestrujesz aplikację poza katalogiem. W przypadkach, gdy aplikacja jest zarejestrowana poza katalogiem, wartość domyślna to Microsoft Entra multitenant i osobiste konta Microsoft.
Konta w dowolnym katalogu organizacyjnym	Wybierz tę opcję, jeśli aplikacja jest przeznaczona dla wszystkich klientów biznesowych i edukacyjnych. Ta opcja mapuje na wielodostępne tylko firmy Microsoft. Jeśli aplikacja została zarejestrowana jako tylko jedna dzierżawa firmy Microsoft, możesz ją zaktualizować tak, aby była wielodostępna i z powrotem do jednej dzierżawy za pomocą okienka Uwierzytelnianie .
Konta w dowolnym katalogu organizacyjnym i konta osobiste Microsoft	Wybierz tę opcję, aby kierować aplikację do najszerszego grona odbiorców. Ta opcja mapuje na konta Microsoft Entra multitenant i osobiste konta Microsoft. Jeśli zarejestrowano aplikację jako wielodostępne i osobiste konta Microsoft Entra, nie możesz zmienić tego w interfejsie użytkownika. Zamiast tego do zmiany obsługiwanych typów kont należy użyć edytora manifestów aplikacji.

Identyfikator URI przekierowania (opcjonalnie) — wybierz typ kompilowania aplikacji, **Sieć Web lub Publiczny klient (mobilny i klasyczny), a następnie wprowadź identyfikator URI przekierowania (lub adres URL odpowiedzi) dla aplikacji.
- W przypadku aplikacji internetowej podaj podstawowy adres URL aplikacji. Na przykład ciąg http://localhost:31544 może być adresem URL aplikacji internetowej uruchomionej na komputerze lokalnym. Użytkownicy mogą użyć tego adresu URL, aby zalogować się do aplikacji klienta internetowego.
- W przypadku aplikacji klienckich publicznych podaj identyfikator URI używany przez firmę Microsoft Entra ID do zwracania odpowiedzi tokenu. Podaj wartość specyficzną dla Twojej aplikacji, np. myapp://auth.
Aby zobaczyć konkretne przykłady dotyczące aplikacji internetowych lub natywnych, zapoznaj się z przewodnikami Szybki start.

Po zakończeniu wybierz pozycję Rejestruj.

Zezwól aplikacji na dostęp do aplikacji Microsoft Defender dla Chmury i przypisz do niej uprawnienie "Odczyt alertów":
- Na stronie aplikacji wybierz pozycję Uprawnienia>interfejsu API Dodaj interfejsy API uprawnień>Moja organizacja używa> typu Microsoft Cloud App Security, a następnie wybierz pozycję Microsoft Cloud App Security.
- Uwaga: usługa Microsoft Cloud App Security nie jest wyświetlana na oryginalnej liście. Zacznij zapisywać swoją nazwę w polu tekstowym, aby zobaczyć, jak się pojawi. Pamiętaj, aby wpisać tę nazwę, mimo że produkt ma teraz nazwę Defender dla Chmury Apps.
- Wybierz pozycję Delegowane uprawnienia>Badanie.Odczyt> wybierz pozycję Dodaj uprawnienia
- Ważna uwaga: wybierz odpowiednie uprawnienia. Investigation.Read jest tylko przykładem. Aby uzyskać informacje o innych zakresach uprawnień, zobacz Obsługiwane zakresy uprawnień
  - Aby określić, które uprawnienia są potrzebne, wyświetl sekcję Uprawnienia w interfejsie API, który cię interesuje.
- Wybierz pozycję Udziel zgody administratora
  
  Uwaga: za każdym razem, gdy dodajesz uprawnienie, musisz wybrać pozycję Udziel zgody administratora, aby nowe uprawnienie zaczęły obowiązywać.
Zanotuj identyfikator aplikacji i identyfikator dzierżawy:
- Na stronie aplikacji przejdź do pozycji Przegląd i skopiuj następujące informacje:

Obsługiwane zakresy uprawnień

Nazwa uprawnień	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, zaktualizuj lub usuń. Wykonaj wszystkie akcje jednostek.	Lista działań, pobieranie, opinia Lista alertów, pobieranie, oznaczanie jako przeczytane/nieprzeczytane Lista jednostek, pobieranie, pobieranie drzewa Lista podsieci
Investigation.manage	Wykonaj wszystkie akcje investigation.read oprócz zarządzania alertami i zakresami adresów IP.	Lista działań, pobieranie, opinia Lista alertów, pobieranie, oznaczanie jako przeczytane/nieprzeczytane, zamknij 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świetlanie listy raportów i kategorii odnajdywania.	Lista alertów, pobieranie, oznaczanie jako przeczytane/nieprzeczytane Raporty listy odnajdywania, lista kategorii raportów
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, zamknij Raporty listy odnajdywania, lista kategorii raportów Przekazywanie pliku odnajdywania, generowanie skryptu bloku
Settings.read	Wyświetlanie listy 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

Pobranie tokenu dostępu

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

Przy użyciu języka C#

Skopiuj/wklej następującą klasę w aplikacji.
Użyj metody AcquireUserTokenAsync z identyfikatorem aplikacji, identyfikatorem dzierżawy i uwierzytelnianiem uzyskaj token.

Uwaga

W poniższym przykładzie kodu pokazano, jak uzyskać token przy użyciu przepływu nazwy użytkownika i hasła, firma Microsoft zaleca używanie bezpieczniejszych przepływów uwierzytelniania w środowisku produkcyjnym.

namespace MDA
{
    using System.Net.Http;
    using System.Text;
    using System.Threading.Tasks;
    using Newtonsoft.Json.Linq;

    public static class MDAUtils
    {
        private const string Authority = "https://login.microsoftonline.com";

        private const string MDAId = "05a65629-4c1b-48c1-a78b-804c4abdd4af";
        private const string Scope = "Investigation.read";

        public static async Task<string> AcquireUserTokenAsync(string username, string password, string appId, string tenantId)
        {
            using (var httpClient = new HttpClient())
            {
                var urlEncodedBody = $"scope={MDAId}/{Scope}&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>();
                }
            }
        }
    }
}

Sprawdzanie poprawności tokenu

Sprawdź, czy masz prawidłowy token:

Skopiuj/wklej do JWT token uzyskany w poprzednim kroku, aby zdekodować go
Sprawdź, czy otrzymasz oświadczenie "scp" z żądanymi uprawnieniami aplikacji
Na poniższym zrzucie ekranu możesz zobaczyć zdekodowany token uzyskany z aplikacji w samouczku:

Uzyskiwanie dostępu do interfejsu API usługi Microsoft Defender dla Chmury Apps przy użyciu tokenu

Wybierz interfejs API, którego chcesz użyć. Aby uzyskać więcej informacji, zobacz interfejs API usługi Defender dla Chmury Apps.
Ustaw nagłówek autoryzacji w żądaniu HTTP wysyłanym do elementu nośnego {token}" (element nośny jest schematem autoryzacji)
Czas wygaśnięcia tokenu wynosi 1 godzinę (można wysłać więcej niż jedno żądanie z tym samym tokenem)

Przykład wysyłania żądania w celu 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

Udostępnij za pośrednictwem