Verwenden von Microsoft Defender für Endpunkt-APIs

Artikel
06/25/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 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 im Namen eines Benutzers zu erhalten.

Wenn Sie programmgesteuerten Zugriff auf Microsoft Defender für Endpunkt ohne Benutzer benötigen, lesen Sie Zugreifen auf Microsoft Defender für Endpunkt mit Anwendungskontext.

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

Microsoft Defender für Endpunkt macht einen Großteil seiner Daten und Aktionen über eine Reihe programmgesteuerter APIs verfügbar. Diese APIs ermöglichen es Ihnen, Workflows zu automatisieren und Innovationen basierend auf den Funktionen von Microsoft Defender für Endpunkt 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 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 für Microsoft Defender für Endpunkt abrufen und das Token überprüfen.

Hinweis

Wenn Sie im Namen eines Benutzers auf die Microsoft Defender für Endpunkt-API zugreifen, benötigen Sie die richtige Anwendungsberechtigung und Benutzerberechtigung. Wenn Sie nicht mit Benutzerberechtigungen für Microsoft Defender für Endpunkt 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

Melden Sie sich beim Azure-Portal an.
Navigieren Sie zu Microsoft Entra ID>App-Registrierungen>Neue Registrierung.

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 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. Diese Option ist nicht verfügbar, wenn Sie die Anwendung nicht in einem Verzeichnis registrieren. Diese Option ist nur einem Einzelnen Mandanten von Microsoft Entra zugeordnet. Diese Option ist die Standardoption, es sei denn, Sie registrieren die App außerhalb eines Verzeichnisses. In Fällen, in denen die App außerhalb eines Verzeichnisses registriert ist, ist die Standardeinstellung mehrinstanzenfähige und persönliche Microsoft-Konten von Microsoft Entra.
Konten in einem beliebigen Organisationsverzeichnis	Wählen Sie diese Option, wenn Sie alle Kunden aus dem Unternehmens- und Bildungsbereich ansprechen möchten. Diese Option wird einem mehrinstanzenfähigen Microsoft Entra-Mandanten zugeordnet. Wenn Sie die App als Nur-Mandant von Microsoft Entra registriert haben, können Sie sie über das Blatt Authentifizierung auf mehrinstanzenfähige Microsoft Entra und zurück auf einen einzelnen Mandanten aktualisieren.
Konten in allen Organisationsverzeichnissen und persönliche Microsoft-Konten	Verwenden Sie diese Option, um die breiteste Kundengruppe anzusprechen. Diese Option wird mehrinstanzenfähigen und persönlichen Microsoft-Konten von Microsoft Entra zugeordnet. Wenn Sie die App als mehrinstanzenfähige und persönliche Microsoft Entra-Konten registriert haben, können Sie dies auf der Benutzeroberfläche nicht ä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 der Microsoft Entra-ID verwendet wird, um Tokenantworten zurückzugeben. 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.

Gewähren Sie Ihrer Anwendung den Zugriff auf Microsoft Defender für Endpunkt, und weisen Sie ihr die Berechtigung "Warnungen lesen" zu:
- Wählen Sie auf ihrer Anwendungsseite API-Berechtigungen> Berechtigungs-APIs >hinzufügenaus, diemeine Organisation 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 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 die Berechtigung hinzufügen, müssen Sie die Option Zustimmung erteilen auswählen, damit die neue Berechtigung wirksam wird.
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 im 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 die Microsoft Defender für Endpunkt-API

Wählen Sie die API aus, die Sie verwenden möchten: Unterstützte Microsoft 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 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

Tipp

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

Freigeben über

Verwenden von Microsoft Defender für Endpunkt-APIs

App erstellen

Abrufen eines Zugriffstokens

Verwenden von C#

Überprüfen des Tokens

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

Siehe auch

Feedback

Zusätzliche Ressourcen