Freigeben über

Zugreifen auf Microsoft Defender for Cloud Apps-API mit Benutzerkontext

  • Artikel

Auf dieser Seite wird beschrieben, wie Sie eine Anwendung erstellen, um programmgesteuerten Zugriff auf Defender for Cloud Apps im Namen eines Benutzers zu erhalten.

Wenn Sie programmgesteuerten Zugriff Microsoft Defender for Cloud Apps ohne Benutzer benötigen, finden Sie weitere Informationen unter Access Microsoft Defender for Cloud Apps with application context (Zugriff auf Microsoft Defender for Cloud Apps mit Anwendungskontext).

Wenn Sie nicht sicher sind, welchen Zugriff Sie benötigen, lesen Sie die Seite Einführung.

Microsoft Defender for Cloud Apps macht einen Großteil seiner Daten und Aktionen über eine Reihe programmgesteuerter APIs verfügbar. Diese APIs ermöglichen es Ihnen, Workflows zu automatisieren und Innovationen basierend auf Microsoft Defender for Cloud Apps Funktionen zu entwickeln. Für den API-Zugriff ist eine OAuth2.0-Authentifizierung erforderlich. Weitere Informationen finden Sie unter OAuth 2.0-Autorisierungscodefluss.

Im Allgemeinen müssen Sie die folgenden Schritte ausführen, um die APIs zu verwenden:

  • Erstellen einer Microsoft Entra-Anwendung
  • Abrufen eines Zugriffstokens mithilfe dieser Anwendung
  • Verwenden des Tokens für den Zugriff auf Defender for Cloud Apps API

Auf dieser Seite wird erläutert, wie Sie eine Microsoft Entra Anwendung erstellen, ein Zugriffstoken zum Microsoft Defender for Cloud Apps abrufen und das Token überprüfen.

Hinweis

Wenn Sie im Namen eines Benutzers auf Microsoft Defender for Cloud Apps API zugreifen, benötigen Sie die richtige Anwendungsberechtigung und Benutzerberechtigung. Wenn Sie nicht mit Benutzerberechtigungen für Microsoft Defender for Cloud Apps vertraut sind, finden Sie weitere Informationen unter Verwalten des Administratorzugriffs.

Tipp

Wenn Sie über die Berechtigung zum Ausführen einer Aktion im Portal verfügen, verfügen Sie über die Berechtigung zum Ausführen der Aktion in der API.

App erstellen

  1. Registrieren Sie im Microsoft Entra Admin Center eine neue Anwendung. Weitere Informationen finden Sie unter Schnellstart: Registrieren einer Anwendung beim Microsoft Entra Admin Center.

  2. Geben Sie auf der daraufhin angezeigten Seite Anwendung registrieren die Registrierungsinformationen für Ihre Anwendung ein:

    • Name : Geben Sie einen aussagekräftigen Anwendungsnamen ein, der benutzern der App angezeigt wird.

    • Unterstützte Kontotypen: Wählen Sie aus, welche Konten von Ihrer Anwendung unterstützt werden sollen.

      Unterstützte Kontotypen Beschreibung
      Nur Konten in diesem Organisationsverzeichnis Wählen Sie diese Option aus, wenn Sie eine Branchenanwendung erstellen. Diese Option ist nicht verfügbar, wenn Sie die Anwendung nicht in einem Verzeichnis registrieren.

      Diese Option wird Microsoft Entra nur einem Mandanten zugeordnet.

      Sofern Sie die App nicht außerhalb eines Verzeichnisses registrieren, ist dies die Standardoption. In Fällen, in denen die App außerhalb eines Verzeichnisses registriert ist, ist die Standardeinstellung Microsoft Entra mehrinstanzenfähigen und persönlichen Microsoft-Konten.
      Konten in einem beliebigen Organisationsverzeichnis Wählen Sie diese Option, wenn Sie alle Kunden aus dem Unternehmens- und Bildungsbereich ansprechen möchten.

      Diese Option wird einem Microsoft Entra mehrinstanzenfähig zugeordnet.

      Wenn Sie die App als Microsoft Entra Nur-Mandant registriert haben, können Sie sie über den Bereich Authentifizierung auf Microsoft Entra mehrinstanzenfähig und zurück auf einen einzelnen Mandanten aktualisieren.
      Konten in allen Organisationsverzeichnissen und persönliche Microsoft-Konten Verwenden Sie diese Option, um die breiteste Kundengruppe anzusprechen.

      Diese Option wird Microsoft Entra mehrinstanzenfähigen und persönlichen Microsoft-Konten zugeordnet.

      Wenn Sie die App als Microsoft Entra mehrinstanzenfähigen und persönlichen Microsoft-Konten registriert haben, können Sie dies auf der Benutzeroberfläche nicht ändern. In diesem Fall müssen die unterstützten Kontotypen mithilfe des Anwendungsmanifest-Editors geändert werden.

    • Umleitungs-URI (optional): Wählen Sie den Typ der App aus, die Sie erstellen, **Web oder Öffentlicher Client (mobiler & Desktop)), und geben Sie dann den Umleitungs-URI (oder die Antwort-URL) für Ihre Anwendung ein.

      • Geben Sie für Webanwendungen die Basis-URL Ihrer App an. http://localhost:31544 kann beispielsweise die URL für eine Web-App sein, die auf einem lokalen Computer ausgeführt wird. Benutzer können diese URL nutzen, um sich an einer Webclientanwendung anzumelden.
      • Geben Sie für öffentliche Clientanwendungen den URI an, der von Microsoft Entra ID zum Zurückgeben von Tokenantworten verwendet wird. Geben Sie einen für Ihre Anwendung spezifischen Wert ein (beispielsweise myapp://auth).

      Spezifische Beispiele für Webanwendungen oder native Anwendungen finden Sie in unseren Schnellstartanleitungen.

      Wenn Sie so weit sind, klicken Sie auf Registrieren.

  3. Gewähren Sie Ihrer Anwendung den Zugriff auf Microsoft Defender for Cloud Apps, und weisen Sie ihr die Berechtigung "Warnungen lesen" zu:

    • Wählen Sie auf der Anwendungsseite API-Berechtigungen> Berechtigungs-APIs >hinzufügenaus, diemein organization verwendet>, geben Sie Microsoft Cloud App Security ein, und wählen Sie dann Microsoft Cloud App Security aus.

    • Hinweis: Microsoft Cloud App Security wird nicht in der ursprünglichen Liste angezeigt. Beginnen Sie mit dem Schreiben des Namens in das Textfeld, damit er angezeigt wird. Stellen Sie sicher, dass Sie diesen Namen eingeben, auch wenn das Produkt jetzt Defender for Cloud Apps heißt.

      Screenshot: Hinzufügen von Berechtigungen

    • Wählen Sie Delegierte Berechtigungen>Untersuchung aus.Lesen> wählen Sie Berechtigungen hinzufügen aus.

      Screenshot: Hinzufügen von Anwendungsberechtigungen

    • Wichtiger Hinweis: Wählen Sie die relevanten Berechtigungen aus. Investigation.Read ist nur ein Beispiel. Informationen zu anderen Berechtigungsbereichen finden Sie unter Unterstützte Berechtigungsbereiche.

      • Um zu ermitteln, welche Berechtigung Sie benötigen, sehen Sie sich den Abschnitt Berechtigungen in der API an, die Sie aufrufen möchten.

    • Wählen Sie Administratoreinwilligung erteilen aus.

      Hinweis: Jedes Mal, wenn Sie die Berechtigung hinzufügen, müssen Sie Administratoreinwilligung erteilen auswählen, damit die neue Berechtigung wirksam wird.

      Screenshot: Erteilen von Administratorberechtigungen

  4. Notieren Sie sich Ihre Anwendungs-ID und Ihre Mandanten-ID:

    • Navigieren Sie auf der Anwendungsseite zu Übersicht , und kopieren Sie die folgenden Informationen:

      Screenshot der erstellten App-ID.

Unterstützte Berechtigungsbereiche

Berechtigungsname Beschreibung Unterstützte Aktionen
Investigation.read Führen Sie alle unterstützten Aktionen für Aktivitäten und Warnungen mit Ausnahme von Schließen von Warnungen aus.
Ip-Adressbereiche anzeigen, aber nicht hinzufügen, aktualisieren oder löschen.

Führen Sie alle Entitätsaktionen aus.		 Aktivitätsliste, Abrufen, Feedback
Warnungen auflisten, abrufen, als gelesen/ungelesen markieren
Entitäten auflisten, abrufen, Struktur abrufen
Subnetzliste
Investigation.manage Führen Sie alle investigation.read-Aktionen zusätzlich zum Verwalten von Warnungen und IP-Adressbereichen aus. Aktivitätsliste, Abrufen, Feedback
Warnungen auflisten, abrufen, als gelesen/ungelesen markieren, schließen
Entitäten auflisten, abrufen, Struktur abrufen
Subnetzliste, Erstellen/Aktualisieren/Löschen
Discovery.read Führen Sie alle unterstützten Aktionen für Aktivitäten und Warnungen mit Ausnahme von Schließen von Warnungen aus.
Auflisten von Ermittlungsberichten und -kategorien.		 Warnungen auflisten, abrufen, als gelesen/ungelesen markieren
Ermittlungslistenberichte, Listenberichtskategorien
Discovery.manage Discovery.read-Berechtigungen
Schließen von Warnungen, Hochladen von Ermittlungsdateien und Generieren von Blockskripts		 Warnungen auflisten, abrufen, als gelesen/ungelesen markieren, schließen
Ermittlungslistenberichte, Listenberichtskategorien
Ermittlungsdateiupload, Blockskript generieren
Settings.read Ip-Adressbereiche auflisten. Subnetzliste
Settings.manage Auflisten und Verwalten von IP-Adressbereichen. Subnetzliste, Erstellen/Aktualisieren/Löschen

Abrufen eines Zugriffstokens

Weitere Informationen zu Microsoft Entra Token finden Sie unter Microsoft Entra Tutorial.

Verwenden von C#

  • Kopieren Sie die folgende Klasse in Ihre Anwendung, und fügen Sie sie ein.
  • Verwenden Sie die AcquireUserTokenAsync-Methode mit Ihrer Anwendungs-ID, Mandanten-ID und Authentifizierung, um ein Token abzurufen.

Hinweis

Während das folgende Codebeispiel veranschaulicht, wie Ein Token mithilfe des Benutzernamen- und Kennwortflusses abgerufen wird, empfiehlt Microsoft die Verwendung sichererer Authentifizierungsflows in einer Produktionsumgebung.

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>();
                }
            }
        }
    }
}

Überprüfen des Tokens

Vergewissern Sie sich, dass Sie ein richtiges Token erhalten haben:

  • Kopieren Sie das Token, das Sie im vorherigen Schritt erhalten haben, und fügen Sie es in JWT ein, um es zu decodieren.

  • Überprüfen Sie, ob Sie einen "scp"-Anspruch mit den gewünschten App-Berechtigungen erhalten.

  • Im folgenden Screenshot sehen Sie ein decodiertes Token, das von der App im Tutorial abgerufen wurde:

    Screenshot der Tokenüberprüfung.

Verwenden des Tokens für den Zugriff auf die Microsoft Defender for Cloud Apps-API

  • Wählen Sie die API aus, die Sie verwenden möchten. Weitere Informationen finden Sie unter Defender for Cloud Apps-API.

  • Legen Sie den Autorisierungsheader in der HTTP-Anforderung fest, die Sie an "Bearer {token}" senden (Bearer ist das Autorisierungsschema).

  • Die Ablaufzeit des Tokens beträgt 1 Stunde (Sie können mehr als eine Anforderung mit demselben Token senden).

  • Beispiel für das Senden einer Anforderung zum Abrufen einer Liste von Warnungen mithilfe von 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

Siehe auch