Freigeben über

Zugreifen 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 programmgesteuerten Zugriff auf Defender for Cloud Apps im Namen eines Benutzers benötigen, finden Sie weitere Informationen unter Abrufen des Zugriffs mit Benutzerkontext. Wenn Sie nicht sicher sind, welchen Zugriff Sie benötigen, lesen Sie die Seite Verwalten von API-Token .

Microsoft Defender for Cloud Apps macht einen Großteil seiner Daten und Aktionen über eine Reihe programmgesteuerter APIs verfügbar. Diese APIs helfen Ihnen, Workflows zu automatisieren und Innovationen basierend auf 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 Sie eine Microsoft Entra-Anwendung.
  • Rufen Sie mithilfe dieser Anwendung ein Zugriffstoken ab.
  • Verwenden Sie das Token, um auf 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: Registrieren einer Anwendung beim Microsoft Entra Admin Center.

  2. Um Ihrer App den Zugriff auf Defender for Cloud Apps zu ermöglichen und ihr die Berechtigung "Alle Warnungen lesen" zuzuweisen, wählen Sie auf der Anwendungsseite API-Berechtigungen> Berechtigungs-APIs >hinzufügen,die mein organization verwendet>, geben Sie Microsoft Cloud App Security ein, und wählen Sie dann Microsoft aus. Cloud App Security.

    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 der Berechtigung

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

      Screenshot: Hinzufügen der App-Berechtigung

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

  3. Wählen Sie Administratoreinwilligung erteilen aus.

    Hinweis

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

    Screenshot: Erteilen von Administratorberechtigungen

  4. Um der Anwendung ein Geheimnis hinzuzufügen, wählen Sie Zertifikate & Geheimnisse aus, wählen Sie Neuer geheimer Clientschlüssel aus, fügen Sie dem Geheimnis eine Beschreibung hinzu, und wählen Sie dann Hinzufügen aus.

    Hinweis

    Nachdem Sie Hinzufügen ausgewählt haben, wählen Sie den generierten Geheimniswert kopieren aus. Sie können diesen Wert nach dem Verlassen nicht mehr abrufen.

    Screenshot: Erstellen eines App-Schlüssels

  5. Notieren Sie sich Ihre Anwendungs-ID und Ihre Mandanten-ID. Navigieren Sie auf der Anwendungsseite zu Übersicht, und kopieren Sie die Anwendungs-ID (Client-ID) und die Verzeichnis-ID (Mandant).

    Screenshot der erstellten App-ID.

  6. Nur für Microsoft Defender for Cloud Apps Partner. Legen Sie fest, dass Ihre App mehrinstanzenfähig 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 Nutzung erstellen, die nur mit Ihren eigenen Daten interagiert). So legen Sie die mehrinstanzenfähige App fest:

    • Wechseln Sie zu Authentifizierung, und fügen Sie als Umleitungs-URI hinzuhttps://portal.azure.com.

    • Wählen Sie unten auf der Seite unter Unterstützte Kontotypen die Anwendungsgenehmigung 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 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.

    Der Zustimmungslink wird wie folgt gebildet:

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

    Dabei wird 0000000000-0000-00000-00000000000000 durch Ihre Anwendungs-ID ersetzt.

Fertig. Sie haben eine Anwendung erfolgreich registriert! Weitere Informationen zum Abrufen und Überprüfen von Token finden Sie unten in den Beispielen.

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 im tutorial Microsoft Entra.

PowerShell verwenden

# 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

Weitere Informationen finden Sie unter Microsoft Authentication Library (MSAL) für 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 geheimen Azure-Anwendungsschlüssel fest.
  3. Legen Sie TENANT_ID auf die Azure-Mandanten-ID des Kunden fest, der 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 der folgenden 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 erhalten haben, und fügen Sie es in JWT ein, um es zu decodieren.
  2. Überprüfen Sie, ob Sie den Anspruch "rollen" 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 Microsoft Defender for Cloud Apps Rollen abgerufen wurde:

Screenshot der Tokenüberprüfung.

Verwenden des Tokens für den Zugriff auf 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 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