Create einer App mit Partnerzugriff auf Microsoft Defender XDR-APIs

  • 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 Microsoft Entra-App erstellen, die programmgesteuerten Zugriff auf Microsoft Defender XDR im Namen von Benutzern über mehrere Mandanten hinweg hat. Mehrinstanzenfähige Apps sind für die Bereitstellung großer Benutzergruppen nützlich.

Wenn Sie programmgesteuerten Zugriff auf Microsoft Defender XDR im Namen eines einzelnen Benutzers benötigen, lesen Sie Create einer App, um im Namen eines Benutzers auf Microsoft Defender XDR-APIs zuzugreifen. Wenn Sie Zugriff benötigen, ohne dass ein Benutzer explizit definiert ist (z. B. wenn Sie eine Hintergrund-App oder einen Daemon schreiben), lesen Sie Create eine App, um ohne Benutzer auf Microsoft Defender XDR zuzugreifen. 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.

Da diese App mehrinstanzenfähig ist, benötigen Sie auch die Administratoreinwilligung von jedem Mandanten im Namen seiner Benutzer.

In diesem Artikel wird folgendes erläutert:

  • Create einer mehrinstanzenfähigen Microsoft Entra-Anwendung
  • Holen Sie sich die autorisierte Zustimmung Ihres Benutzeradministrators ein, damit Ihre Anwendung auf die Microsoft Defender XDR der benötigten Ressourcen zugreifen kann.
  • Abrufen eines Zugriffstokens für Microsoft Defender XDR
  • Überprüfen des Tokens

Microsoft Defender XDR macht einen Großteil seiner Daten und Aktionen über eine Reihe programmgesteuerter APIs verfügbar. Diese APIs helfen Ihnen, Arbeitsabläufe zu automatisieren und Innovationen basierend auf Microsoft Defender XDR 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:

  • Create eine mehrinstanzenfähige Microsoft Entra-Anwendung.
  • Lassen Sie sich von Ihrem Benutzeradministrator autorisieren (zustimmung), damit Ihre Anwendung auf Microsoft Defender XDR benötigten Ressourcen zugreifen kann.
  • Rufen Sie mithilfe dieser Anwendung ein Zugriffstoken ab.
  • Verwenden Sie das Token, um auf Microsoft Defender XDR-API zuzugreifen.

In den folgenden Schritten wird beschrieben, wie Sie eine mehrinstanzenfähige Microsoft Entra-Anwendung erstellen, ein Zugriffstoken zum Microsoft Defender XDR abrufen und das Token überprüfen.

Create der mehrinstanzenfähigen App

  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.

    Registrierungsabschnitt einer Anwendung im Microsoft Defender-Portal

  3. Im Registrierungsformular:

    • Wählen Sie einen Namen für Ihre Anwendung aus.
    • Wählen Sie unter Unterstützte Kontotypendie Option Konten in einem beliebigen Organisationsverzeichnis (beliebiges Microsoft Entra Verzeichnis) – Mehrinstanzenfähig aus.
    • Füllen Sie den Abschnitt Umleitungs-URI aus. Wählen Sie Web aus, und geben Sie den Umleitungs-URI als an https://portal.azure.com.

    Nachdem Sie das Formular ausgefüllt haben, wählen Sie Registrieren aus.

    Registrierungsabschnitte einer Anwendung im Microsoft Defender-Portal

  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.

    Abschnitt

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

    Berechtigungsbereich einer Anwendung im Microsoft Defender-Portal

    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.

  6. 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.

    Ein Abschnitt zum Erteilen der Administratoreinwilligung im Microsoft Defender-Portal

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

    Tipp

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

    Abschnitt zum Hinzufügen von Geheimnissen im Microsoft Defender-Portal

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

    Bereich

  9. Fügen Sie die Anwendung dem Mandanten Ihres Benutzers hinzu.

    Da Ihre Anwendung im Namen Ihrer Benutzer mit Microsoft Defender XDR interagiert, muss sie für jeden Mandanten genehmigt werden, für den Sie sie verwenden möchten.

    Ein globaler Administrator aus dem Mandanten Ihres Benutzers muss den Zustimmungslink anzeigen und Ihre Anwendung genehmigen.

    Der Zustimmungslink hat das folgende Format:

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

    Die Ziffern 00000000-0000-0000-0000-000000000000 sollten durch Ihre Anwendungs-ID ersetzt werden.

    Nachdem Sie auf den Zustimmungslink geklickt haben, melden Sie sich mit dem globalen Administrator des Mandanten des Benutzers an, und stimmen Sie der Anwendung zu.

    Die Seite

    Außerdem müssen Sie Ihren Benutzer nach seiner Mandanten-ID fragen. Die Mandanten-ID ist einer der Bezeichner, die zum Abrufen von Zugriffstoken verwendet werden.

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

Abrufen eines Zugriffstokens

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

Wichtig

Obwohl sie in den Beispielen in diesem Abschnitt dazu ermutigen, zu Testzwecken geheime Werte einzufügen, sollten Sie geheimnisse niemals in eine Anwendung hartcodieren , die in der Produktion ausgeführt wird. Ein Drittanbieter könnte Ihr Geheimnis für den Zugriff auf Ressourcen verwenden. Mithilfe von Azure Key Vault können Sie dazu beitragen, die Geheimnisse Ihrer App zu schützen. Ein praktisches Beispiel für den Schutz Ihrer App finden Sie unter Verwalten von Geheimnissen in Ihren Server-Apps mit Azure Key Vault.

Tipp

Verwenden Sie in den folgenden Beispielen die Mandanten-ID eines Benutzers, um zu testen, dass das Skript funktioniert.

Abrufen eines Zugriffstokens mithilfe von PowerShell

# This code gets the application context token and saves it to a file named "Latest-token.txt" under the current directory.

$tenantId = '' # Paste your directory (tenant) ID here
$clientId = '' # Paste your application (client) ID here
$appSecret = '' # Paste your own app secret here to test, then store it in a safe place!

$resourceAppIdUri = 'https://api.security.microsoft.com'
$oAuthUri = "https://login.windows.net/$tenantId/oauth2/token"

$authBody = [Ordered] @{
    resource = $resourceAppIdUri
    client_id = $clientId
    client_secret = $appSecret
    grant_type = 'client_credentials'
}

$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token

Out-File -FilePath "./Latest-token.txt" -InputObject $token

return $token

Abrufen eines Zugriffstokens mit C#

Hinweis

Der folgende Code wurde mit Nuget Microsoft.Identity.Client 3.19.8 getestet.

Wichtig

Das NuGet-Paket Microsoft.IdentityModel.Clients.ActiveDirectory und Azure AD-Authentifizierung Library (ADAL) sind veraltet. Seit dem 30. Juni 2020 wurden keine neuen Features hinzugefügt. Wir empfehlen Ihnen dringend, ein Upgrade durchzuführen. Weitere Informationen finden Sie im Migrationsleitfaden .

  1. Create eine neue Konsolenanwendung.

  2. Installieren Sie NuGet Microsoft.Identity.Client.

  3. Fügen Sie die folgende Zeile 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, clientId, appSecret):

    string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here
string appId = "11111111-1111-1111-1111-111111111111"; // 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 = https://api.securitycenter.microsoft.com;

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

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

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

string token = authResult.AccessToken;

Abrufen eines Zugriffstokens mithilfe von Python

import json
import urllib.request
import urllib.parse

tenantId = '' # Paste your directory (tenant) ID here
clientId = '' # Paste your application (client) ID here
appSecret = '' # Paste your own app secret here to test, then store it in a safe place, such as the Azure Key Vault!

url = "https://login.windows.net/%s/oauth2/token" % (tenantId)

resourceAppIdUri = 'https://api.security.microsoft.com'

body = {
    'resource' : resourceAppIdUri,
    'client_id' : clientId,
    'client_secret' : appSecret,
    'grant_type' : 'client_credentials'
}

data = urllib.parse.urlencode(body).encode("utf-8")

req = urllib.request.Request(url, data)
response = urllib.request.urlopen(req)
jsonResponse = json.loads(response.read())
aadToken = jsonResponse["access_token"]

Abrufen eines Zugriffstokens mithilfe von curl

Hinweis

Curl ist auf Windows 10 Version 1803 und höher vorinstalliert. Für andere Versionen von Windows laden Sie das Tool direkt von der offiziellen curl-Website herunter, und installieren Sie es.

  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 Benutzers fest, der Ihre App für den Zugriff auf Microsoft Defender XDR 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=https://securitycenter.onmicrosoft.com/windowsatpservice/.default" -d "client_secret=%CLIENT_SECRET%" "https://login.microsoftonline.com/%TENANT_ID%/oauth2/v2.0/token" -k

Eine erfolgreiche Antwort sieht wie folgt aus:

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

Überprüfen des Tokens

  1. Kopieren Sie das Token, und fügen Sie es in die Website JWT des JSON-Webtokens 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:

Bereich

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.