Freigeben über

Zugriff auf Microsoft Defender for Cloud Apps mit Anwendungskontext

  • Artikel

Auf dieser Seite wird beschrieben, wie Sie eine Anwendung erstellen, um programmgesteuerten Zugriff auf Defender for Cloud Apps ohne Benutzer zu erhalten. Wenn Sie programmatischen Zugriff auf Defender for Cloud Apps im Namen eines Benutzers benötigen, lesen Sie den Abschnitt Zugriff mit Benutzerkontext erhalten. Wenn Sie nicht sicher sind, welchen Zugriff Sie benötigen, lesen Sie die Seite API-Token verwalten.

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 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
  • Rufen Sie mithilfe dieser Anwendung ein Zugriffstoken ab.
  • Verwenden Sie das Token, um auf die Defender for Cloud Apps-API zuzugreifen.

In diesem Artikel 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.

Erstellen einer App für Defender for Cloud Apps

  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. Um Ihrer App den Zugriff auf Defender für Cloud-Apps zu ermöglichen und die Berechtigung Alle Warnungen lesen zuzuweisen, wählen Sie API Berechtigungen>Berechtigung hinzufügen>APIs die meine Organisation nutzt>, geben Sie Microsoft Cloud App Security ein, und wählen Sie Microsoft Cloud App Security.

    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 vom Hinzufügen einer Berechtigung.

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

      Screenshot vom Hinzufügen einer App-Berechtigung.

      Sie müssen die entsprechenden Berechtigungen auswählen. 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.

  3. 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. Wenn Sie der Anwendung einen geheimen Schlüssel hinzufügen möchten, wählen Sie Zertifikate& Geheime Schlüssel, wählen Sie Neuer geheimer Clientschlüssel, fügen Sie dem Schlüssel eine Beschreibung hinzu und wählen Sie dann Hinzufügen.

    Hinweis

    Nachdem Sie Hinzufügen ausgewählt haben, wählen Sie den generierten geheimen Wert kopieren. Nach dem Verlassen dieses Blatts können Sie ihn nicht mehr abrufen.

    Screenshot des Erstellens eines App-Schlüssels.

  5. Notieren Sie sich Ihre Anwendungs-ID und Ihre Mandanten-ID. Gehen Sie auf Ihrer App-Seite zu Übersicht und kopieren Sie die Anwendungs- (Client-ID) ID und die Verzeichnis- (Mandanten-) ID.

    Screenshot der erstellten App-ID.

  6. Nur für Microsoft Defender for Cloud Apps Partner. Legen Sie fest, dass Ihre App mehrfach mandantenübergreifend ist (nach Zustimmung in allen Mandanten verfügbar). Dies ist für Drittanbieter-Apps erforderlich (z. B. wenn Sie eine App erstellen, die im Mandanten mehrerer Kunden ausgeführt werden soll). Dies ist nicht erforderlich, wenn Sie einen Dienst erstellen, den Sie nur in Ihrem Mandanten ausführen möchten (z. B. wenn Sie eine Anwendung für ihre eigene Verwendung erstellen, die nur mit Ihren eigenen Daten interagiert). So richten Sie Ihre App mehrinstanzenfähig ein:

    • Wechseln Sie zur Authentifizierung, und fügen Sie https://portal.azure.com als Umleitungs-URIhinzu.

    • Wählen Sie unten auf der Seite unter Unterstützte Kontotypen die Einwilligung für die Anwendung Konten in einem beliebigen Organisationsverzeichnis für Ihre mehrinstanzenfähige App aus.

    Ihre Anwendung muss in jedem Mandanten genehmigt werden, in dem Sie sie verwenden möchten. Dies liegt daran, dass Ihre Anwendung mit Defender for Cloud Apps im Namen Ihres Kunden interagiert.

    Sie (oder Ihr Kunde, wenn Sie eine Drittanbieter-App schreiben) müssen den Zustimmungslink auswählen und Ihre App genehmigen. Die Zustimmung sollte mit einem Benutzer erfolgen, der über Administratorrechte in Active Directory verfügt.

    Die Zustimmungslink wird wie folgt erstellt:

    https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true

    Dabei wird 00000000-0000-0000-0000-000000000000 durch Ihre Anwendungs-ID ersetzt.

Das war's! Sie haben eine Anwendung erfolgreich registriert! Für Tokenerhalt und -validierung finden Sie unten Beispiele.

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 PowerShell

# This script acquires the App Context Token and stores it in the variable $token for later use in the script.
# Paste your Tenant ID, App ID, and App Secret (App key) into the indicated quotes below.

$tenantId = '' ### Paste your tenant ID here
$appId = '' ### Paste your Application ID here
$appSecret = '' ### Paste your Application key here

$resourceAppIdUri = '05a65629-4c1b-48c1-a78b-804c4abdd4af'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
$authBody = [Ordered] @{
    resource = "$resourceAppIdUri"
    client_id = "$appId"
    client_secret = "$appSecret"
    grant_type = 'client_credentials'
}
$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token

Verwenden von C#

Der folgende Code wurde mit NuGet Microsoft.Identity.Client 4.47.2 getestet.

  1. Erstellen Sie eine neue Konsolenanwendung.

  2. Installieren Sie NuGet Microsoft.Identity.Client.

  3. Fügen Sie Folgendes hinzu:

    using Microsoft.Identity.Client;

  4. Kopieren Sie den folgenden Code, und fügen Sie ihn in Ihre App ein (vergessen Sie nicht, die drei Variablen zu aktualisieren: tenantId, appId, appSecret):

    string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here
string appId = "00001111-aaaa-2222-bbbb-3333cccc4444"; // Paste your own app ID here
string appSecret = "22222222-2222-2222-2222-222222222222"; // Paste your own app secret here for a test, and then store it in a safe place!
const string authority = "https://login.microsoftonline.com";
const string audience = "05a65629-4c1b-48c1-a78b-804c4abdd4af";

IConfidentialClientApplication myApp = ConfidentialClientApplicationBuilder.Create(appId).WithClientSecret(appSecret).WithAuthority($"{authority}/{tenantId}").Build();

List scopes = new List() { $"{audience}/.default" };

AuthenticationResult authResult = myApp.AcquireTokenForClient(scopes).ExecuteAsync().GetAwaiter().GetResult();

string token = authResult.AccessToken;

Verwenden von Python

Mehr unter Microsoft Authentication Library (MSAL) for Python

Verwenden von Curl

Hinweis

Im folgenden Verfahren wird davon ausgegangen, dass Curl für Windows bereits auf Ihrem Computer installiert ist.

  1. Öffnen Sie eine Eingabeaufforderung, und legen Sie CLIENT_ID auf Ihre Azure-Anwendungs-ID fest.
  2. Legen Sie CLIENT_SECRET auf Ihren Azure-Anwendungsschlüssel fest.
  3. Legen Sie TENANT_ID auf die Azure-Mandanten-ID des Kunden fest, die Ihre App für den Zugriff auf Defender for Cloud Apps verwenden möchte.
  4. Führen Sie den folgenden Befehl aus:
curl -i -X POST -H "Content-Type:application/x-www-form-urlencoded" -d "grant_type=client_credentials" -d "client_id=%CLIENT_ID%" -d "scope=05a65629-4c1b-48c1-a78b-804c4abdd4af/.default" -d "client_secret=%CLIENT_SECRET%" "https://login.microsoftonline.com/%TENANT_ID%/oauth2/v2.0/token" -k

Sie erhalten eine Antwort in folgender Form:

{"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn <truncated> aWReH7P0s0tjTBX8wGWqJUdDA"}

Überprüfen des Tokens

Stellen Sie sicher, dass Sie das richtige Token erhalten haben:

  1. Kopieren Sie das Token, das Sie im vorherigen Schritt in JWT erhalten haben, und fügen Sie es ein, um es zu decodieren.
  2. Überprüfen Sie, ob Sie einen „Rollen"-Anspruch mit den gewünschten Berechtigungen erhalten
  3. In der folgenden Abbildung sehen Sie ein decodiertes Token, das von einer App mit Berechtigungen für alle Rollen von Microsoft Defender for Cloud Apps erworben wurde:

Screenshot der Token-Überprüfung

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

  1. Wählen Sie die API aus, die Sie verwenden möchten. Weitere Informationen finden Sie unter Defender for Cloud Apps APIs.
  2. Legen Sie den Autorisierungsheader in der HTTP-Anforderung fest, die Sie an „Bearer {token}" senden (Bearer ist das Autorisierungsschema).
  3. Die Ablaufzeit des Tokens beträgt eine Stunde. Sie können mehrere Anforderungen mit demselben Token senden.

Im Folgenden finden Sie ein 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