Erstellen einer App für den Zugriff auf Microsoft Defender für Endpunkt ohne Benutzer
Gilt für:
- Microsoft Defender für Endpunkt Plan 1
- Microsoft Defender für Endpunkt Plan 2
- Microsoft Defender für Unternehmen
Wichtig
Erweiterte Suchfunktionen sind in Defender for Business nicht enthalten.
Möchten Sie Microsoft Defender für Endpunkt ausprobieren? Registrieren Sie sich für eine kostenlose Testversion.
Hinweis
Wenn Sie ein US Government-Kunde sind, verwenden Sie die URIs, die unter Microsoft Defender für Endpunkt für US Government-Kunden aufgeführt sind.
Tipp
Um die Leistung zu verbessern, können Sie den Server näher an Ihrem geografischen Standort verwenden:
- us.api.security.microsoft.com
- eu.api.security.microsoft.com
- uk.api.security.microsoft.com
- au.api.security.microsoft.com
- swa.api.security.microsoft.com
Auf dieser Seite wird beschrieben, wie Sie eine Anwendung erstellen, um programmgesteuerten Zugriff auf Defender für Endpunkt ohne Benutzer zu erhalten. Wenn Sie programmgesteuerten Zugriff auf Defender für Endpunkt 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 Erste Schritte.
Microsoft Defender für Endpunkt macht einen Großteil seiner Daten und Aktionen über eine Reihe programmgesteuerter APIs verfügbar. Diese APIs helfen Ihnen dabei, Arbeitsabläufe zu automatisieren und Innovationen basierend auf defender für Endpunkt-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 die Defender für Endpunkt-API zuzugreifen.
In diesem Artikel wird erläutert, wie Sie eine Microsoft Entra-Anwendung erstellen, ein Zugriffstoken für Microsoft Defender für Endpunkt abrufen und das Token überprüfen.
Wichtig
Microsoft empfiehlt die Verwendung von Rollen mit den geringsten Berechtigungen. Dies trägt zur Verbesserung der Sicherheit für Ihre Organisation bei. Globaler Administrator ist eine Rolle mit hohen Berechtigungen, die auf Notfallszenarien beschränkt werden sollte, wenn Sie keine vorhandene Rolle verwenden können.
App erstellen
Melden Sie sich beim Azure-Portal mit einem Benutzer an, der über die Rolle "Globaler Administrator" verfügt.
Navigieren Sie zu Microsoft Entra ID>App-Registrierungen>Neue Registrierung.
Wählen Sie im Registrierungsformular einen Namen für Ihre Anwendung und dann Registrieren aus.
Um Ihrer App den Zugriff auf Defender für Endpunkt zu ermöglichen und ihr die Berechtigung "Alle Warnungen lesen" zuzuweisen, wählen Sie auf der Anwendungsseite API-Berechtigungen> Berechtigungs-APIs >hinzufügen,diemeine Organisation verwendet>, geben Sie WindowsDefenderATP ein, und wählen Sie dann WindowsDefenderATP aus.
Hinweis
WindowsDefenderATPwird nicht in der ursprünglichen Liste angezeigt. Beginnen Sie mit dem Schreiben des Namens in das Textfeld, damit er angezeigt wird.
Wählen Sie Anwendungsberechtigungen>Alert.Read.All und dann Berechtigungen hinzufügen aus.
Wählen Sie die entsprechenden Berechtigungen aus.
Read All Alertsist nur ein Beispiel. Hier sind einige Beispiele:- Um erweiterte Abfragen auszuführen, wählen Sie die Berechtigung aus
Run advanced queries. - Wählen Sie die Berechtigung aus, um ein Gerät zu isolieren
Isolate machine. - Um zu ermitteln, welche Berechtigung Sie benötigen, sehen Sie sich den Abschnitt Berechtigungen in der API an, die Sie aufrufen möchten.
- Um erweiterte Abfragen auszuführen, wählen Sie die Berechtigung aus
Wählen Sie Zustimmung erteilen aus.
Hinweis
Jedes Mal, wenn Sie eine Berechtigung hinzufügen, müssen Sie Zustimmung erteilen auswählen, damit die neue Berechtigung wirksam wird.
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.
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.
Notieren Sie sich Ihre Anwendungs-ID und Ihre Mandanten-ID. Navigieren Sie auf der Anwendungsseite zu Übersicht , und kopieren Sie Folgendes.
Nur für Microsoft Defender für Endpunktpartner. Legen Sie ihre App auf mehrinstanzenfähig fest (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). Führen Sie die folgenden Schritte aus, um Ihre App als mehrinstanzenfähig festzulegen:
Wechseln Sie zu Authentifizierung, und fügen Sie als Umleitungs-URI hinzu
https://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 für Endpunkt 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=trueDabei
00000000-0000-0000-0000-000000000000wird durch Ihre Anwendungs-ID ersetzt.
Fertig. Sie haben erfolgreich eine Bewerbung 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 Microsoft Entra-Tutorial.
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
$sourceAppIdUri = 'https://api.securitycenter.microsoft.com/.default'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/v2.0/token"
$authBody = [Ordered] @{
scope = "$sourceAppIdUri"
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
$token
Verwenden Sie C#:
Der folgende Code wurde mit NuGet Microsoft.Identity.Client 3.19.8 getestet.
Wichtig
Das NuGet-Paket Microsoft.IdentityModel.Clients.ActiveDirectory und die Azure AD-Authentifizierungsbibliothek (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 .
Erstellen Sie eine neue Konsolenanwendung.
Installieren Sie NuGet Microsoft.Identity.Client.
Fügen Sie Folgendes hinzu:
using Microsoft.Identity.Client;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 = "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;
Verwenden von Python
Weitere Informationen finden Sie unter Abrufen von Token mithilfe von Python.
Verwenden von Curl
Hinweis
Im folgenden Verfahren wird davon ausgegangen, dass Curl für Windows bereits auf Ihrem Computer installiert ist.
Öffnen Sie eine Eingabeaufforderung, und legen Sie auf Ihre Azure-Anwendungs-ID fest
CLIENT_ID.Legen Sie
CLIENT_SECRETauf Ihren geheimen Azure-Anwendungsschlüssel fest.Legen Sie
TENANT_IDauf die Azure-Mandanten-ID des Kunden fest, der Ihre App für den Zugriff auf Defender für Endpunkt verwenden möchte.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" -kSie erhalten eine Antwort, die dem folgenden Codeausschnitt ähnelt:
{"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:
Kopieren Sie das Token, das Sie im vorherigen Schritt erhalten haben, und fügen Sie es in JWT ein, um es zu decodieren.
Überprüfen Sie, ob Sie einen Rollenanspruch mit den gewünschten Berechtigungen erhalten.
In der folgenden Abbildung sehen Sie ein decodiertes Token, das von einer App mit Berechtigungen für alle Rollen von Microsoft Defender für Endpunkt abgerufen wurde:
Verwenden des Tokens für den Zugriff auf die Microsoft Defender für Endpunkt-API
Wählen Sie die API aus, die Sie verwenden möchten. Weitere Informationen finden Sie unter Unterstützte Defender für Endpunkt-APIs.
Legen Sie den Autorisierungsheader in der Anforderung fest, an
Bearer {token}diehttpSie senden (Bearer ist das Autorisierungsschema).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://api.securitycenter.microsoft.com/api/alerts");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
var response = httpClient.SendAsync(request).GetAwaiter().GetResult();
// Do something useful with the response
Siehe auch
- Unterstütze Microsoft Defender für Endpoint-APIs
- Zugreifen auf Microsoft Defender für Endpunkt im Namen eines Benutzers
Tipp
Möchten Sie mehr erfahren? Wenden Sie sich an die Microsoft-Sicherheitscommunity in unserer Tech Community: Microsoft Defender for Endpoint Tech Community.
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für