Create einer App für den Zugriff auf Microsoft Defender XDR-APIs im Namen eines Benutzers

  • Artikel

Gilt für:

  • Microsoft Defender XDR

Wichtig

Einige Informationen beziehen sich auf Vorabversionen von Produkten, die vor der kommerziellen Veröffentlichung noch erheblich geändert werden können. Microsoft übernimmt mit diesen Informationen keinerlei Gewährleistung, sei sie ausdrücklich oder konkludent.

Auf dieser Seite wird beschrieben, wie Sie eine Anwendung erstellen, um programmgesteuerten Zugriff auf Microsoft Defender XDR im Namen eines einzelnen Benutzers zu erhalten.

Wenn Sie programmgesteuerten Zugriff auf Microsoft Defender XDR ohne definierten Benutzer benötigen (z. B. wenn Sie eine Hintergrund-App oder einen Daemon schreiben), lesen Sie Create einer App, um ohne Benutzer auf Microsoft Defender XDR zuzugreifen. Wenn Sie Zugriff für mehrere Mandanten bereitstellen müssen, z. B. wenn Sie eine große organization oder eine Gruppe von Kunden bedienen, lesen Sie Create einer App mit Partnerzugriff auf Microsoft Defender XDR-APIs. Wenn Sie nicht sicher sind, welche Art von Zugriff Sie benötigen, lesen Sie Erste Schritte.

Microsoft Defender XDR macht einen Großteil seiner Daten und Aktionen über eine Reihe programmgesteuerter APIs verfügbar. Mithilfe dieser APIs können Sie Workflows automatisieren und die Funktionen von Microsoft Defender XDR nutzen. Für diesen API-Zugriff ist die OAuth2.0-Authentifizierung erforderlich. Weitere Informationen finden Sie unter OAuth 2.0-Autorisierungscodefluss.

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

  • Create einer Microsoft Entra-Anwendung.
  • Rufen Sie mithilfe dieser Anwendung ein Zugriffstoken ab.
  • Verwenden Sie das Token, um auf Microsoft Defender XDR-API zuzugreifen.

In diesem Artikel wird folgendes erläutert:

  • Create einer Microsoft Entra-Anwendung
  • Abrufen eines Zugriffstokens für Microsoft Defender XDR
  • Überprüfen des Tokens

Hinweis

Wenn Sie im Namen eines Benutzers auf Microsoft Defender XDR API zugreifen, benötigen Sie die richtigen Anwendungsberechtigungen und Benutzerberechtigungen.

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. Melden Sie sich bei Azure als Benutzer mit der Rolle "Globaler Administrator " an.

  2. Navigieren Sie zu Microsoft Entra ID>App-Registrierungen>Neue Registrierung.

    Die Option

  3. Wählen Sie im Formular einen Namen für Ihre Anwendung aus, geben Sie die folgenden Informationen für den Umleitungs-URI ein, und wählen Sie dann Registrieren aus.

    Der Bereich

  4. Wählen Sie auf der Anwendungsseite API-Berechtigungen> Berechtigungs-APIs >hinzufügenaus,die meine organization verwendet>, geben Sie Microsoft Threat Protection ein, und wählen Sie Microsoft Threat Protection aus. Ihre App kann jetzt auf Microsoft Defender XDR zugreifen.

    Tipp

    Microsoft Threat Protection ist ein früherer Name für Microsoft Defender XDR und wird nicht in der ursprünglichen Liste angezeigt. Sie müssen damit beginnen, seinen Namen in das Textfeld zu schreiben, damit er angezeigt wird.

    Bereich

    • Wählen Sie Delegierte Berechtigungen aus. Wählen Sie die relevanten Berechtigungen für Ihr Szenario aus (z. B. Incident.Read), und wählen Sie dann Berechtigungen hinzufügen aus.

      Bereich

    Hinweis

    Sie müssen die relevanten Berechtigungen für Ihr Szenario auswählen. Alle Vorfälle lesen ist nur ein Beispiel. Um zu ermitteln, welche Berechtigung Sie benötigen, sehen Sie sich den Abschnitt Berechtigungen in der API an, die Sie aufrufen möchten.

    Um instance erweiterte Abfragen auszuführen, wählen Sie die Berechtigung "Erweiterte Abfragen ausführen" aus. Wählen Sie zum Isolieren eines Geräts die Berechtigung "Computer isolieren" aus.

  5. Wählen Sie Administratoreinwilligung erteilen aus. Jedes Mal, wenn Sie eine Berechtigung hinzufügen, müssen Sie Administratoreinwilligung erteilen auswählen, damit sie wirksam wird.

    Bereich

  6. Notieren Sie ihre Anwendungs-ID und Ihre Mandanten-ID an einem sicheren Ort. Sie werden auf der Anwendungsseite unter Übersicht aufgeführt.

    Bereich

Abrufen eines Zugriffstokens

Weitere Informationen zu Microsoft Entra Token finden Sie im tutorial Microsoft Entra.

Abrufen eines Zugriffstokens im Namen eines Benutzers mithilfe von PowerShell

Verwenden Sie die MSAL.PS-Bibliothek, um Zugriffstoken mit delegierten Berechtigungen abzurufen. Führen Sie die folgenden Befehle aus, um das Zugriffstoken im Namen eines Benutzers abzurufen:

Install-Module -Name MSAL.PS # Install the MSAL.PS module from PowerShell Gallery

$TenantId = " " # Paste your directory (tenant) ID here.
$AppClientId="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # Paste your application (client) ID here.

$MsalParams = @{
   ClientId = $AppClientId
   TenantId = $TenantId
   Scopes   = 'https://graph.microsoft.com/User.Read.All','https://graph.microsoft.com/Files.ReadWrite','https://api.securitycenter.windows.com/AdvancedQuery.Read'
}

$MsalResponse = Get-MsalToken @MsalParams
$AccessToken  = $MsalResponse.AccessToken
 
$AccessToken # Display the token in PS console

Überprüfen des Tokens

  1. Kopieren Sie das Token, und fügen Sie es in JWT ein, um es zu decodieren.
  2. Stellen Sie sicher, dass der Rollenanspruch innerhalb des decodierten Tokens die gewünschten Berechtigungen enthält.

In der folgenden Abbildung sehen Sie ein decodiertes Token, das von einer App mit Incidents.Read.Allden Berechtigungen , Incidents.ReadWrite.Allund AdvancedHunting.Read.All abgerufen wurde:

Abschnitt

Verwenden des Tokens für den Zugriff auf die Microsoft Defender XDR-API

  1. Wählen Sie die API aus, die Sie verwenden möchten (Incidents oder erweiterte Suche). Weitere Informationen finden Sie unter Unterstützte Microsoft Defender XDR-APIs.
  2. Legen Sie in der HTTP-Anforderung, die Sie senden möchten, den Autorisierungsheader auf "Bearer" <token>fest, der Bearer ist das Autorisierungsschema, und das Token ist Ihr überprüftes Token.
  3. Das Token läuft innerhalb einer Stunde ab. Sie können während dieser Zeit mehr als eine Anforderung mit demselben Token senden.

Das folgende Beispiel zeigt, wie Sie eine Anforderung senden, um eine Liste von Vorfällen mithilfe von C# abzurufen.

    var httpClient = new HttpClient();
    var request = new HttpRequestMessage(HttpMethod.Get, "https://api.security.microsoft.com/api/incidents");

    request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

    var response = httpClient.SendAsync(request).GetAwaiter().GetResult();

Tipp

Möchten Sie mehr erfahren? Engage mit der Microsoft-Sicherheitscommunity in unserer Tech Community: Microsoft Defender XDR Tech Community.