Erstellen einer App für den Zugriff auf Microsoft Defender XDR-APIs im Namen eines Benutzers
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 Erstellen einer App für den Zugriff auf Microsoft Defender XDR ohne Benutzer. Wenn Sie Zugriff für mehrere Mandanten bereitstellen müssen , z. B. wenn Sie eine große Organisation oder eine Gruppe von Kunden bedienen, lesen Sie Erstellen 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:
- Erstellen Sie eine Microsoft Entra-Anwendung.
- Rufen Sie mithilfe dieser Anwendung ein Zugriffstoken ab.
- Verwenden Sie das Token für den Zugriff auf die Microsoft Defender XDR-API.
In diesem Artikel wird folgendes erläutert:
- Erstellen einer Microsoft Entra-Anwendung
- Abrufen eines Zugriffstokens für Microsoft Defender XDR
- Überprüfen des Tokens
Hinweis
Wenn Sie im Namen eines Benutzers auf die 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
Melden Sie sich bei Azure als Benutzer mit der Rolle "Globaler Administrator " an.
Navigieren Sie zu Microsoft Entra ID>App-Registrierungen>Neue Registrierung.
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.
- Anwendungstyp: Öffentlicher Client
- Umleitungs-URI:https://portal.azure.com
Wählen Sie auf der Anwendungsseite API-Berechtigungen> Berechtigungs-APIs >hinzufügenaus, diemeine Organisation 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.
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.
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.
Wenn Sie beispielsweise erweiterte Abfragen ausführen möchten, wählen Sie die Berechtigung "Erweiterte Abfragen ausführen" aus. Um ein Gerät zu isolieren, wählen Sie die Berechtigung "Computer isolieren" aus.
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.
Notieren Sie ihre Anwendungs-ID und Ihre Mandanten-ID an einem sicheren Ort. Sie werden auf der Anwendungsseite unter Übersicht aufgeführt.
Abrufen eines Zugriffstokens
Weitere Informationen zu Microsoft Entra-Token finden Sie im Microsoft Entra-Tutorial.
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
- Kopieren Sie das Token, und fügen Sie es in JWT ein, um es zu decodieren.
- 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.All
den Berechtigungen , Incidents.ReadWrite.All
und AdvancedHunting.Read.All
abgerufen wurde:
Verwenden des Tokens für den Zugriff auf die Microsoft Defender XDR-API
- 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.
- 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. - 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();
Verwandte Artikel
- Übersicht über Microsoft Defender XDR-APIs
- Zugreifen auf die Microsoft Defender XDR-APIs
- Erstellen einer "Hello World"-App
- Erstellen einer App für den Zugriff auf Microsoft Defender XDR ohne Benutzer
- Erstellen einer App mit mehrinstanzenfähigem Partnerzugriff auf Microsoft Defender XDR-APIs
- Informationen zu API-Grenzwerten und -Lizenzierung
- Grundlegendes zu Fehlercodes
- OAuth 2.0-Autorisierung für Benutzeranmeldung und API-Zugriff
Tipp
Möchten Sie mehr erfahren? Wenden Sie sich an die Microsoft Security-Community in unserer Tech Community: Microsoft Defender XDR Tech Community.