Freigeben über

Auf die Microsoft Defender for Cloud Apps-API mit Benutzerkontext zugreifen

  • 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 auf Microsoft Defender for Cloud Apps ohne Benutzer benötigen, lesen Sie Access 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 von programmgesteuerten APIs verfügbar. Diese APIs ermöglichen es Ihnen, Arbeitsabläufe zu automatisieren und Innovationen basierend auf den Funktionen von Microsoft Defender for Cloud Apps zu automatisieren. Der API-Zugriff erfordert die OAuth2.0-Authentifizierung. Weitere Informationen finden Sie unter OAuth 2.0-Autorisierungscodeflow.

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 Sie das Token um auf die Defender for Cloud Apps-API zuzugreifen

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

Hinweis

Wenn Sie im Namen eines Benutzers auf die Microsoft Defender for Cloud Apps-API zugreifen, benötigen Sie die richtige Anwendungsberechtigung und Benutzerberechtigung. Wenn Sie mit Den Benutzerberechtigungen für Microsoft Defender for Cloud Apps nicht vertraut sind, lesen Sie 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.

Erstellen einer App

  1. Registrieren Sie im Microsoft Entra Admin Center eine neue Anwendung. Weitere Informationen finden Sie unter Schnellstart: Eine Anwendung bei der Microsoft Entra-Admin Center registrieren.

  2. Wenn die Seite Registrieren einer Anwendung angezeigt wird, geben Sie die Registrierungsinformationen Ihrer Anwendung ein:

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

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

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

      Diese Option ist Microsoft Entra-only Einzelmandanten zugeordnet.

      Sofern Sie die App nicht außerhalb eines Verzeichnisses registrieren, ist dies die Standardoption. Wird die App außerhalb eines Verzeichnisses registriert, werden standardmäßig mehrinstanzenfähige Microsoft Entra-Konten und persönliche Microsoft-Konten verwendet.
      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 mehrinstanzenfähigen Microsoft Entra-Konto zugeordnet.

      Wenn Sie die App als reine Microsoft Entra-App mit einem einzelnen Mandanten registriert haben, können Sie sie über das Blatt Authentifizierung in eine Microsoft Entra-App mit mehreren Mandanten (und wieder zurück in eine App mit einem einzelnen Mandanten) verwandeln.
      Konten in allen Organisationsverzeichnissen und persönliche Microsoft-Konten Wählen Sie diese Option aus, um die meisten Kunden anzusprechen.

      Diese Option ist für Microsoft Entra-Apps mit mehreren Mandanten und für persönliche Microsoft-Konten vorgesehen.

      Wenn Sie die App als Microsoft Entra-App mit mehreren Mandanten und für persönliche Microsoft-Konten registriert haben, können Sie dies über die Benutzeroberfläche nicht ändern. Stattdessen müssen Sie den Anwendungsmanifest-Editor verwenden, um die unterstützten Kontotypen zu ändern.

    • Umleitungs-URI (optional): Wählen Sie die Art der App aus, die Sie erstellen (Web oder Öffentlicher Client (Mobilgerät und 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 Token-Antworten 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. Erlauben Sie Ihrer Anwendung den Zugriff auf Microsoft Defender for Cloud Apps, und weisen Sie sie der Berechtigung „Warnungen lesen“ zu:

    • Wählen Sie auf Ihrer Anwendungsseite API-Berechtigungen>Hinzufügen von Berechtigungen> aus, APIs, die meine Organisation verwendet>, geben Sie dann 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 im Textfeld, damit es angezeigt wird. Geben Sie diesen Namen ein, auch wenn das Produkt jetzt Defender for Cloud-Apps genannt wird.

      Screenshot: Hinzufügen von Berechtigungen

    • Wählen Sie Delegierte Berechtigungen>Investigation.Read> aus, und wählen Sie Berechtigungen hinzufügen aus.

      Screenshot des Hinzufügens von Anwendungsberechtigungen.

    • Wichtiger Hinweis: Wählen Sie die relevanten Berechtigungen aus. Investigation.Read ist nur ein Beispiel. Weitere Berechtigungsbereiche finden Sie unter Unterstützte Berechtigungsumfänge

      • Um zu ermitteln, welche Berechtigung Sie benötigen, schauen 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 eine Berechtigung hinzufügen, müssen Sie Administratorzustimmung erteilen auswählen, damit die neue Berechtigung wirksam wird.

      Screenshot der Gewährung von Administratorberechtigungen.

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

    • Wechseln Sie auf Ihrer Anwendungsseite zu Übersicht und kopieren Sie die folgenden Informationen:

      Screenshot der erstellten App-ID.

Unterstützte Berechtigungsumfänge

Berechtigungsname Beschreibung Unterstützte Aktionen
Investigation.Read Durchführen aller unterstützten Aktionen für Aktivitäten und Warnungen mit Ausnahme von Schließen von Warnungen.
Anzeigen von IP-Adressbereichen, aber nicht hinzufügen, aktualisieren oder löschen.

Durchführen aller Entitätenaktionen.		 Aktivitätsliste, fetch, Feedback
Warnungsliste, Abrufen, Als gelesen/ungelesen markieren
Entitätenliste, fetch, fetch-Struktur
Subnetzliste
Investigation.manage Ausführen aller Investigation.Read-Aktionen zusätzlich zum Verwalten von Warnungen und IP-Adressbereichen. Aktivitätsliste, fetch, Feedback
Warnungsliste, Abrufen, Als gelesen/ungelesen markieren, Schließen
Entitätenliste, fetch, fetch-Struktur
Subnetzliste, Erstellen/Aktualisieren/Löschen
Discovery.read Durchführen aller unterstützten Aktionen für Aktivitäten und Warnungen mit Ausnahme von Schließen von Warnungen.
Auflisten von Discoveryberichten und Kategorien.		 Warnungsliste, Abrufen, Als gelesen/ungelesen markieren
Discovery-Listenberichte, Listenberichtskategorien
Discovery.manage Discovery.read-Berechtigungen
Schließen von Warnungen, Hochladen von Ermittlungsdateien und Generieren von Blockskripts		 Warnungsliste, Abrufen, Als gelesen/ungelesen markieren, Schließen
Discovery-Listenberichte, Listenberichtskategorien
Hochladen von Ermittlungsdateien, generieren eines Blockskripts
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/Einfügen Sie die folgende Klasse in Ihrer Anwendung.
  • Verwenden Sie die AcquireUserTokenAsync-Methode mit Ihrer Anwendungs-ID, Mandanten-ID und die Authentifizierungsdetails, um ein Token abzurufen.

Hinweis

Im folgenden Codebeispiel wird zwar veranschaulicht, wie ein Token mithilfe des Benutzernamens- und Kennwortflows abgerufen wird, microsoft empfiehlt jedoch, in einer Produktionsumgebung sicherere Authentifizierungsflüsse zu verwenden.

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

Bestätigen Sie, dass Sie ein richtiges Token erhalten haben:

  • Kopieren/Einfügen des Tokens, das Sie im vorherigen Schritt in JWT erhalten haben, und fügen Sie es 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 Lernprogramm erworben wurde:

    Screenshot der Token-Überprüfung

Einsetzen 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 mehrere Anforderungen mit demselben Token senden)

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