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

Artikel
04/26/2024

Gilt für:

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 bitte die URIs, die in Microsoft Defender for Endpoint 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 for Endpoint 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:

Create einer 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 for Endpoint abrufen und das Token überprüfen.

App erstellen

Melden Sie sich bei Azure 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,die mein organization verwendet>, geben Sie WindowsDefenderATP ein, und wählen Sie dann WindowsDefenderATP aus.

Hinweis

WindowsDefenderATP wird 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.

Sie müssen die entsprechenden Berechtigungen auswählen. "Alle Warnungen lesen" ist nur ein Beispiel. Zum Beispiel:
- Wählen Sie zum Ausführen erweiterter Abfragen die Berechtigung "Erweiterte Abfragen ausführen" aus.
- Um ein Gerät zu isolieren, wählen Sie die Berechtigung "Computer isolieren" aus.
- Um zu ermitteln, welche Berechtigung Sie benötigen, sehen Sie sich den Abschnitt Berechtigungen in der API an, die Sie aufrufen möchten.
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 for Endpoint Partner. 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). So legen Sie eine mehrinstanzenfähige App 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.
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=true
```
Dabei wird 0000000000-0000-00000-00000000000000 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 tutorial Microsoft Entra.

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

Create 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 CLIENT_ID auf Ihre Azure-Anwendungs-ID fest.
Legen Sie CLIENT_SECRET auf Ihren geheimen Azure-Anwendungsschlüssel fest.
Legen Sie TENANT_ID auf 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" -k

Sie erhalten eine Antwort in der folgenden Form:

{"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 den Anspruch "roles" 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 Microsoft Defender for Endpoint abgerufen wurde:

Verwenden des Tokens für den Zugriff auf Microsoft Defender for Endpoint-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 HTTP-Anforderung fest, die Sie an "Bearer {token}" 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