Udostępnij za pośrednictwem

Dostęp do interfejsu API Microsoft Defender for Cloud Apps przy użyciu kontekstu użytkownika

  • Artykuł

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

Jeśli potrzebujesz dostępu programowego Microsoft Defender for Cloud Apps bez użytkownika, zapoznaj się z artykułem Access Microsoft Defender for Cloud Apps with application context (Dostęp Microsoft Defender for Cloud Apps z kontekstem aplikacji).

Jeśli nie masz pewności, jakiego dostępu potrzebujesz, przeczytaj stronę Wprowadzenie.

Microsoft Defender for Cloud Apps uwidacznia wiele swoich danych i akcji za pośrednictwem zestawu programowych interfejsów API. Te interfejsy API umożliwiają automatyzowanie przepływów pracy i wprowadzanie innowacji w oparciu o Microsoft 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:

  • Tworzenie aplikacji Microsoft Entra
  • Uzyskiwanie tokenu dostępu przy użyciu tej aplikacji
  • Uzyskiwanie dostępu do interfejsu API Defender for Cloud Apps przy użyciu tokenu

Na tej stronie wyjaśniono, jak utworzyć aplikację Microsoft Entra, uzyskać token dostępu do Microsoft Defender for Cloud Apps i zweryfikować token.

Uwaga

Podczas uzyskiwania dostępu do interfejsu API Microsoft Defender for Cloud Apps w imieniu użytkownika potrzebne są odpowiednie uprawnienia aplikacji i uprawnienia użytkownika. Jeśli nie znasz uprawnień użytkownika na Microsoft Defender for Cloud Apps, zobacz Zarządzanie dostępem administratora.

Porada

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

Tworzenie aplikacji

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

  2. Po wyświetleniu strony Rejestrowanie aplikacji wprowadź informacje o rejestracji aplikacji:

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

    • Obsługiwane typy kont — wybierz konta, które chcesz obsługiwać w aplikacji.

      Obsługiwane typy kont Opis
      Konta tylko w tym katalogu organizacyjnym Wybierz tę opcję, jeśli tworzysz aplikację biznesową (LOB). Ta opcja nie jest dostępna, jeśli nie rejestrujesz aplikacji w katalogu.

      Ta opcja jest mapowana na Microsoft Entra tylko jedną dzierżawę.

      Jest to opcja domyślna, chyba że rejestrujesz aplikację poza katalogiem. W przypadkach, gdy aplikacja jest zarejestrowana poza katalogiem, ustawieniem domyślnym jest Microsoft Entra wielodostępne i osobiste konta Microsoft.
      Konta w dowolnym katalogu organizacyjnym Wybierz tę opcję, jeśli chcesz kierować dane do wszystkich klientów biznesowych i edukacyjnych.

      Ta opcja jest mapowana na wielodostępną obsługę tylko Microsoft Entra.

      Jeśli aplikacja została zarejestrowana jako jednodostępna tylko Microsoft Entra, możesz ją zaktualizować tak, aby była Microsoft Entra wielodostępna i z powrotem do jednej dzierżawy za pośrednictwem okienka Uwierzytelnianie.
      Konta w dowolnym katalogu organizacyjnym i osobistych kontach Microsoft Wybierz tę opcję, aby kierować dane do najszerszego zestawu klientów.

      Ta opcja jest mapowana na Microsoft Entra wielodostępne i osobiste konta Microsoft.

      Jeśli aplikacja została zarejestrowana jako Microsoft Entra wielodostępnych i osobistych kont Microsoft, nie możesz tego zmienić w interfejsie użytkownika. Zamiast tego należy użyć edytora manifestu aplikacji, aby zmienić obsługiwane typy kont.

    • Identyfikator URI przekierowania (opcjonalnie) — wybierz typ utworzonej aplikacji, **Internetowy lub Publiczny klient (mobilny & desktop), a następnie wprowadź identyfikator URI przekierowania (lub adres URL odpowiedzi) dla aplikacji.

      • W przypadku aplikacji internetowych podaj podstawowy adres URL aplikacji. Może to być na przykład http://localhost:31544 adres URL aplikacji internetowej działającej na komputerze lokalnym. Użytkownicy będą używać tego adresu URL do logowania się do aplikacji klienckiej sieci Web.
      • W przypadku publicznych aplikacji klienckich podaj identyfikator URI używany przez Tożsamość Microsoft Entra do zwracania odpowiedzi tokenu. Wprowadź wartość specyficzną dla aplikacji, taką jak myapp://auth.

      Aby wyświetlić konkretne przykłady aplikacji internetowych lub aplikacji natywnych, zapoznaj się z naszymi przewodnikami Szybki start.

      Po zakończeniu wybierz pozycję Zarejestruj.

  3. Zezwalaj aplikacji na dostęp do Microsoft Defender for Cloud Apps i przypisz jej uprawnienie "Odczyt alertów":

    • Na stronie aplikacji wybierz pozycję Uprawnienia interfejsu API Dodaj interfejsy> APIuprawnień> używane przezmoją 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.

      Zrzut ekranu przedstawiający dodawanie uprawnień.

    • Wybierz pozycję Badanie uprawnień>delegowanych.Przeczytaj> wybierz pozycję Dodaj uprawnienia

      Zrzut ekranu przedstawiający dodawanie uprawnień aplikacji.

    • Ważna uwaga: wybierz 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ć opcję Udziel zgody administratora , aby nowe uprawnienie miało obowiązywać.

      Zrzut ekranu przedstawiający przyznawanie uprawnień administratora.

  4. Zapisz identyfikator aplikacji i identyfikator dzierżawy:

    • Na stronie aplikacji przejdź do pozycji Przegląd i skopiuj następujące informacje:

      Zrzut ekranu przedstawiający utworzony identyfikator aplikacji.

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 języka C#

  • Skopiuj/wklej następującą klasę w aplikacji.
  • Użyj metody AcquireUserTokenAsync z identyfikatorem aplikacji, identyfikatorem dzierżawy i uwierzytelnianiem, aby uzyskać 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życie 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>();
                }
            }
        }
    }
}

Weryfikowanie tokenu

Sprawdź, czy masz prawidłowy token:

  • Skopiuj/wklej do JWT token uzyskany w poprzednim kroku w celu jego dekodowania

  • Sprawdź, czy otrzymasz oświadczenie "scp" z odpowiednimi uprawnieniami aplikacji

  • Na poniższym zrzucie ekranu widać dekodowany token uzyskany z aplikacji w samouczku:

    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 interfejs API Defender for Cloud Apps.

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

  • 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ż