Create einer App für den Zugriff auf Microsoft Defender XDR ohne Benutzer

  • 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 ohne einen definierten Benutzer zu erhalten, z. B. wenn Sie einen Daemon oder Hintergrunddienst erstellen.

Wenn Sie programmgesteuerten Zugriff auf Microsoft Defender XDR im Namen eines oder mehrerer Benutzer benötigen, lesen Sie Create einer App für den Zugriff auf Microsoft Defender XDR APIs im Namen eines Benutzers und 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 Sie das Token.

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.

    Registerkarte

  3. Wählen Sie im Formular einen Namen für Ihre Anwendung und dann Registrieren aus.

  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.

    Registerkarte

  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.

    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.

  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.

    Der Bereich im Zusammenhang mit der Zustimmungserteilung 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.

    Bereich

  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. Nur für Microsoft Defender XDR Partner: Befolgen Sie diese Anweisungen für den Partnerzugriff über die Microsoft Defender XDR-APIs, und legen Sie Ihre App auf mehrinstanzenfähig fest, damit sie in allen Mandanten verfügbar sein kann, sobald Sie die Administratoreinwilligung erhalten haben. Partnerzugriff ist für Drittanbieter-Apps erforderlich , z. B. wenn Sie eine App erstellen, die in 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. eine Anwendung für Ihre eigene Nutzung, die nur mit Ihren eigenen Daten interagiert. So legen Sie ihre App als mehrinstanzenfähig 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.

    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.

    Der globale Active Directory-Administrator für jeden Mandanten muss den Zustimmungslink auswählen und Ihre App genehmigen.

    Der Zustimmungslink weist die folgende Struktur auf:

    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.

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.

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, such as the Azure Key Vault!

$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):

    csharp
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 Kunden 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://api.security.microsoft.com/.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, wobei bearer das Autorisierungsschema und token Ihr überprüftes Token ist.

  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.