Verwenden von Microsoft Defender for Endpoint-APIs

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 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 im Namen eines Benutzers zu erhalten.

Wenn Sie programmgesteuerten Zugriff Microsoft Defender for Endpoint ohne Benutzer benötigen, finden Sie weitere Informationen unter Access Microsoft Defender for Endpoint with application context (Zugriff auf Microsoft Defender for Endpoint mit Anwendungskontext).

Wenn Sie nicht sicher sind, welchen Zugriff Sie benötigen, lesen Sie die Seite Einführung.

Microsoft Defender for Endpoint macht einen Großteil seiner Daten und Aktionen über eine Reihe programmgesteuerter APIs verfügbar. Diese APIs ermöglichen es Ihnen, Arbeitsabläufe zu automatisieren und Innovationen basierend auf Microsoft Defender for Endpoint 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
• Abrufen eines Zugriffstokens mithilfe dieser Anwendung
• Verwenden des Tokens für den Zugriff auf die Defender für Endpunkt-API

Auf dieser Seite wird erläutert, wie Sie eine Microsoft Entra-Anwendung erstellen, ein Zugriffstoken zum Microsoft Defender for Endpoint abrufen und das Token überprüfen.

Hinweis

Wenn Sie im Namen eines Benutzers auf Microsoft Defender for Endpoint API zugreifen, benötigen Sie die richtige Anwendungsberechtigung und Benutzerberechtigung. Wenn Sie mit Benutzerberechtigungen für Microsoft Defender for Endpoint nicht vertraut sind, finden Sie weitere Informationen unter Verwalten des Portalzugriffs mithilfe der rollenbasierten Zugriffssteuerung.

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

1. Melden Sie sich bei Azure mit einem Benutzerkonto an, das über die Rolle "Globaler Administrator " verfügt.

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

   

3. Geben Sie auf der daraufhin angezeigten Seite Anwendung registrieren die Registrierungsinformationen für Ihre Anwendung ein:

   • Name: Geben Sie einen aussagekräftigen Anwendungsnamen ein, der den Benutzern der App angezeigt wird.

   • Unterstützte Kontotypen: Wählen Sie aus, welche Konten von Ihrer Anwendung unterstützt werden sollen.

     
     

     Unterstützte Kontotypen	Beschreibung
     Nur Konten in diesem Organisationsverzeichnis	Wählen Sie diese Option aus, wenn Sie eine Branchenanwendung erstellen. Falls Sie die Anwendung nicht in einem Verzeichnis registrieren, ist diese Option nicht verfügbar. Diese Option wird Microsoft Entra nur einem Mandanten zugeordnet. Sofern Sie die App nicht außerhalb eines Verzeichnisses registrieren, ist dies die Standardoption. In Fällen, in denen die App außerhalb eines Verzeichnisses registriert ist, ist die Standardeinstellung Microsoft Entra mehrinstanzenfähigen und persönlichen Microsoft-Konten.
     Konten in einem beliebigen Organisationsverzeichnis	Wählen Sie diese Option, wenn Sie alle Kunden aus dem Unternehmens- und Bildungsbereich ansprechen möchten. Diese Option ist einem Microsoft Entra mehrinstanzenfähig. Wenn Sie die App als Microsoft Entra Nur-Mandant registriert haben, können Sie sie über das Blatt Authentifizierung so aktualisieren, dass sie Microsoft Entra mehrinstanzenfähig und wieder auf einen einzelnen Mandanten zurückversetzt wird.
     Konten in allen Organisationsverzeichnissen und persönliche Microsoft-Konten	Verwenden Sie diese Option, um die breiteste Kundengruppe anzusprechen. Diese Option wird Microsoft Entra mehrinstanzenfähigen und persönlichen Microsoft-Konten zugeordnet. Wenn Sie die App als Microsoft Entra mehrinstanzenfähigen und persönlichen Microsoft-Konten registriert haben, können Sie dies nicht auf der Benutzeroberfläche ändern. In diesem Fall müssen die unterstützten Kontotypen mithilfe des Anwendungsmanifest-Editors geändert werden.

   • Umleitungs-URI (optional): Wählen Sie die Art der App aus, die Sie erstellen (Web oder Öffentlicher Client (Mobilgerät und Desktop)), und geben Sie dann den Umleitungs-URI (oder die Antwort-URL) für Ihre Anwendung ein.

     • Geben Sie für Webanwendungen die Basis-URL Ihrer App an. http://localhost:31544 kann beispielsweise die URL für eine Web-App sein, die auf einem lokalen Computer ausgeführt wird. Benutzer können diese URL nutzen, um sich an einer Webclientanwendung anzumelden.

     • Geben Sie für öffentliche Clientanwendungen den URI an, der von Microsoft Entra ID zum Zurückgeben von Tokenantworten verwendet wird. Geben Sie einen für Ihre Anwendung spezifischen Wert ein (beispielsweise myapp://auth).

     Spezifische Beispiele für Webanwendungen oder native Anwendungen finden Sie in unseren Schnellstartanleitungen.

     Wenn Sie so weit sind, klicken Sie auf Registrieren.

4. Gewähren Sie Ihrer Anwendung den Zugriff auf Microsoft Defender for Endpoint, und weisen Sie ihr die Berechtigung "Warnungen lesen" zu:

   • Wählen Sie auf der Anwendungsseite API-Berechtigungen> Berechtigungs-APIs >hinzufügenaus,die mein organization verwendet>, geben Sie WindowsDefenderATP ein, und wählen Sie 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 Delegierte Berechtigungen>Warnung aus.Lesen> Wählen Sie Berechtigungen hinzufügen aus.

     

   Wichtig

   Wählen Sie die relevanten Berechtigungen aus. Lesewarnungen sind 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 Computerberechtigung isolieren aus.

   • Um zu bestimmen, 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 die Berechtigung hinzufügen, müssen Sie die Option Zustimmung erteilen auswählen, damit die neue Berechtigung wirksam wird.

     

5. Notieren Sie sich Ihre Anwendungs-ID und Ihre Mandanten-ID.

   Navigieren Sie auf der Anwendungsseite zu Übersicht , und kopieren Sie die folgenden Informationen:

   

Abrufen eines Zugriffstokens

Weitere Informationen zu Microsoft Entra Token finden Sie unter Microsoft Entra Tutorial.

Verwenden von C#

• Kopieren Sie die folgende Klasse in Ihre Anwendung, und fügen Sie sie ein.

• Verwenden Sie die AcquireUserTokenAsync-Methode mit Ihrer Anwendungs-ID, Mandanten-ID, Ihrem Benutzernamen und Kennwort, um ein Token abzurufen.

  namespace WindowsDefenderATP
  {
      using System.Net.Http;
      using System.Text;
      using System.Threading.Tasks;
      using Newtonsoft.Json.Linq;
  
      public static class WindowsDefenderATPUtils
      {
          private const string Authority = "https://login.microsoftonline.com";
  
          private const string WdatpResourceId = "https://api.securitycenter.microsoft.com";
  
          public static async Task<string> AcquireUserTokenAsync(string username, string password, string appId, string tenantId)
          {
              using (var httpClient = new HttpClient())
              {
                  var urlEncodedBody = $"resource={WdatpResourceId}&client_id={appId}&grant_type=password&username={username}&password={password}";
  
                  var stringContent = new StringContent(urlEncodedBody, Encoding.UTF8, "application/x-www-form-urlencoded");
  
                  using (var response = await httpClient.PostAsync($"{Authority}/{tenantId}/oauth2/token", stringContent).ConfigureAwait(false))
                  {
                      response.EnsureSuccessStatusCode();
  
                      var json = await response.Content.ReadAsStringAsync().ConfigureAwait(false);
  
                      var jObject = JObject.Parse(json);
  
                      return jObject["access_token"].Value<string>();
                  }
              }
          }
      }
  }
  

Überprüfen des Tokens

Vergewissern Sie sich, dass Sie ein richtiges 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 "scp"-Anspruch mit den gewünschten App-Berechtigungen erhalten.

• Im folgenden Screenshot sehen Sie ein decodiertes Token, das von der App im Tutorial 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: Unterstützt Microsoft Defender for Endpoint-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 1 Stunde (Sie können mehr als eine Anforderung mit demselben Token senden).

• 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

• Microsoft Defender for Endpoint-APIs
• Zugreifen auf Microsoft Defender for Endpoint mit Anwendungskontext

Tipp

Möchten Sie mehr erfahren? Engage mit der Microsoft-Sicherheitscommunity in unserer Tech Community: Microsoft Defender for Endpoint Tech Community.