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

Artikel
12/29/2023

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

Melden Sie sich mit einem Benutzerkonto mit Globaler Administrator-Rolle bei Azure an.
Navigieren Sie zu Microsoft Entra ID>App-Registrierungen>Neue Registrierung.

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 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 ist einem Microsoft Entra-only Mehrfachmandanten zugeordnet. Wenn Sie die App als reine Microsoft Entra mit einem einzelnen Mandanten registriert haben, können Sie sie über das Panel Authentifizierung in eine Microsoft Entra-App mit mehreren Mandanten umwandeln (und umgekehrt).
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 mit mehreren Mandanten und für persönliche Microsoft-Konten vorgesehen. Wenn Sie die App als mehrinstanzenfähige Microsoft Entra-App und für persönliche Microsoft-Konten registriert haben, können Sie dies nicht über die Benutzeroberfläche ä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.

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.
- Wählen Sie Delegierte Berechtigungen>Investigation.Read> aus, und wählen Sie Berechtigungen hinzufügen
- 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.
Notieren Sie sich Ihre Anwendungs-ID und Ihre Mandanten-ID:
- Wechseln Sie auf Ihrer Anwendungsseite zu Übersicht und kopieren Sie die folgenden Informationen:

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, Benutzernamen und Passwort, um ein Token abzurufen.

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:

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

Freigeben über