Teilen über

Erstellen einer App für den Zugriff auf Microsoft Defender für Endpunkt ohne Benutzer

  • Artikel

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 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
  • ina.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 wenigsten Berechtigungen. Dies trägt zur Verbesserung der Sicherheit für Ihre Organisation bei. Globaler Administrator ist eine hoch privilegierte Rolle, die auf Notfallszenarien beschränkt werden sollte, wenn Sie keine vorhandene Rolle verwenden können.

App erstellen

  1. Melden Sie sich beim Azure-Portal mit einem Benutzer an, der über die Rolle "Globaler Administrator" verfügt.

  2. Navigieren Sie zu Microsoft Entra ID>App-Registrierungen>Neue Registrierung.

    Bereich

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

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

    WindowsDefenderATP wird nicht in der ursprünglichen Liste angezeigt. Beginnen Sie mit dem Schreiben des Namens in das Textfeld, damit er angezeigt wird.

    Bereich

    Wählen Sie Anwendungsberechtigungen>Alert.Read.All und dann Berechtigungen hinzufügen aus.

    Der Bereich

  5. Wählen Sie die entsprechenden Berechtigungen aus. Read All Alerts ist 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 isolierenIsolate machine.
    • Um zu ermitteln, welche Berechtigung Sie benötigen, sehen Sie sich den Abschnitt Berechtigungen in der API an, die Sie aufrufen möchten.

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

    Seite

  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.

    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.

    Die Option

  8. Notieren Sie sich Ihre Anwendungs-ID und Ihre Mandanten-ID. Navigieren Sie auf der Anwendungsseite zu Übersicht , und kopieren Sie Folgendes.

    Die erstellten App- und Mandanten-IDs

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

    1. Wechseln Sie zu Authentifizierung, und fügen Sie als Umleitungs-URI hinzuhttps://portal.azure.com.

    2. 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 00000000-0000-0000-0000-000000000000 wird 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 .

  1. Erstellen Sie eine neue Konsolenanwendung.

  2. Installieren Sie NuGet Microsoft.Identity.Client.

  3. Fügen Sie Folgendes 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, 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.

  1. Öffnen Sie eine Eingabeaufforderung, und legen Sie auf Ihre Azure-Anwendungs-ID fest CLIENT_ID .

  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 Defender für Endpunkt 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

    Sie 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:

  1. Kopieren Sie das Token, das Sie im vorherigen Schritt erhalten haben, und fügen Sie es in JWT ein, um es zu decodieren.

  2. Ü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:

    Der Teil der Tokendetails

Verwenden des Tokens für den Zugriff auf die Microsoft Defender für Endpunkt-API

  1. Wählen Sie die API aus, die Sie verwenden möchten. Weitere Informationen finden Sie unter Unterstützte Defender für Endpunkt-APIs.

  2. Legen Sie den Autorisierungsheader in der Anforderung fest, an Bearer {token} die http Sie senden (Bearer ist das Autorisierungsschema).

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

Tipp

Möchten Sie mehr erfahren? Wenden Sie sich an die Microsoft-Sicherheitscommunity in unserer Tech Community: Microsoft Defender for Endpoint Tech Community.