Partnerzugriff über 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
• ina.api.security.microsoft.com

Auf dieser Seite wird beschrieben, wie Sie eine Microsoft Entra-Anwendung erstellen, um programmgesteuerten Zugriff auf Microsoft Defender for Endpoint im Namen Ihrer Kunden zu erhalten.

Microsoft Defender for Endpoint macht einen Großteil seiner Daten und Aktionen über eine Reihe programmgesteuerter APIs verfügbar. Diese APIs helfen Ihnen, Workflows 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:

1. Erstellen Sie eine mehrinstanzenfähige Microsoft Entra-Anwendung.

2. Lassen Sie sich von Ihrem Kundenadministrator autorisieren(consent) für Ihre Anwendung für den Zugriff auf die benötigten Defender für Endpunkt-Ressourcen.

3. Rufen Sie mithilfe dieser Anwendung ein Zugriffstoken ab.

4. Verwenden Sie das Token, um auf Microsoft Defender for Endpoint-API zuzugreifen.

In den folgenden Schritten erfahren Sie, wie Sie eine Microsoft Entra-Anwendung erstellen, ein Zugriffstoken zum Microsoft Defender for Endpoint 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.

Erstellen der mehrinstanzenfähigen App

1. Melden Sie sich bei Ihrem Azure-Mandanten an.

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

   

3. Im Registrierungsformular:

   • Wählen Sie einen Namen für Ihre Anwendung aus.

   • Unterstützte Kontotypen: Konten in einem beliebigen Organisationsverzeichnis.

   • Umleitungs-URI : Typ: Web, URI: https://portal.azure.com

     

4. Erlauben Sie Ihrer Anwendung, auf Microsoft Defender for Endpoint zuzugreifen, und weisen Sie ihr den minimalen Berechtigungssatz zu, der zum Abschließen der Integration erforderlich ist.

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

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

     

Anfordern von API-Berechtigungen

Um zu ermitteln, welche Berechtigung Sie benötigen, lesen Sie den Abschnitt Berechtigungen in der API, die Sie aufrufen möchten. Zum Beispiel:

• Um erweiterte Abfragen auszuführen, wählen Sie die Berechtigung Erweiterte Abfragen ausführen aus.
• Um ein Gerät zu isolieren, wählen Sie die Berechtigung Computer isolieren aus.

Im folgenden Beispiel verwenden wir die Berechtigung Alle Warnungen lesen :

1. Wählen Sie Anwendungsberechtigungen>Alert.Read.All> unter Berechtigungen hinzufügen aus.

   

2. Wählen Sie Zustimmung erteilen aus.

   • Jedes Mal, wenn Sie die Berechtigung hinzufügen, müssen Sie die Option Zustimmung erteilen auswählen, damit die neue Berechtigung wirksam wird.

   

3. Fügen Sie der Anwendung ein Geheimnis hinzu.

   • Wählen Sie Zertifikate & Geheimnisse aus, fügen Sie dem Geheimnis eine Beschreibung hinzu, und wählen Sie Hinzufügen aus.

   Nachdem Sie Hinzufügen ausgewählt haben, stellen Sie sicher, dass Sie den generierten Geheimniswert kopieren. Sie können es nicht mehr abrufen, nachdem Sie es verlassen haben!

   

4. Notieren Sie sich Ihre Anwendungs-ID:

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

     

5. Fügen Sie die Anwendung dem Mandanten Ihres Kunden hinzu.

   Sie müssen Ihre Anwendung in jedem Kundenmandanten genehmigen, in dem Sie sie verwenden möchten. Diese Genehmigung ist erforderlich, da Ihre Anwendung im Namen Ihres Kunden mit Microsoft Defender for Endpoint Anwendung interagiert.

   Ein Benutzerkonto mit den entsprechenden Berechtigungen für den Mandanten Ihres Kunden muss den Zustimmungslink auswählen und Ihre Anwendung genehmigen.

   Der Zustimmungslink hat folgende Form:

   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 sollte durch Ihre Anwendungs-ID ersetzt werden.

   Nachdem Sie den Zustimmungslink ausgewählt haben, melden Sie sich beim Mandanten des Kunden an, und erteilen Sie dann die Zustimmung für die Anwendung.

   

   Darüber hinaus müssen Sie Ihren Kunden nach seiner Mandanten-ID fragen und sie für die zukünftige Verwendung beim Abrufen des Tokens speichern.

6. Fertig. Sie haben erfolgreich eine Bewerbung registriert! In den folgenden Beispielen finden Sie Informationen zum Abrufen und Überprüfen von Token.

Abrufen eines Zugriffstokenbeispiels

Verwenden Sie zum Abrufen des Zugriffstokens im Namen Ihres Kunden die Mandanten-ID des Kunden für die folgenden Tokenkäufe.

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

Verwendung von PowerShell

# That code gets the App Context Token and save it to a file named "Latest-token.txt" under the current directory
# Paste below your Tenant ID, App ID and App Secret (App key).

$tenantId = '' ### Paste your tenant ID here
$appId = '' ### Paste your Application ID here
$appSecret = '' ### Paste your Application key here

$resourceAppIdUri = 'https://api.securitycenter.microsoft.com'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
$authBody = [Ordered] @{
    resource = "$resourceAppIdUri"
    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
Out-File -FilePath "./Latest-token.txt" -InputObject $token
return $token

Verwenden von C#

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. Informationen zum Upgrade finden Sie im Migrationsleitfaden.

1. Erstellen Sie eine neue Konsolenanwendung.

2. Installieren Sie NuGet Microsoft.Identity.Client.

3. Fügen Sie mithilfe von Code Folgendes hinzu:

    using Microsoft.Identity.Client;
   

   Dieser Code wurde mit NuGet Microsoft.Identity.Clientgetestet.

4. Kopieren Sie den folgenden Code in Ihre Anwendung( vergessen Sie nicht, die drei Variablen zu aktualisieren: tenantId, appIdund 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

Das folgende Verfahren soll Curl für Windows bereits auf Ihrem Computer installiert haben

1. Öffnen Sie ein Befehlsfenster.

2. Legen Sie auf Ihre Azure-Anwendungs-ID fest CLIENT_ID .

3. Legen Sie CLIENT_SECRET auf Ihren geheimen Azure-Anwendungsschlüssel fest.

4. Legen Sie TENANT_ID auf die Azure-Mandanten-ID des Kunden fest, der Ihre Anwendung für den Zugriff auf Microsoft Defender for Endpoint Anwendung verwenden möchte.

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

Vergewissern Sie sich, dass Sie ein korrektes 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. Vergewissern Sie sich, dass Sie einen Rollenanspruch mit den entsprechenden Berechtigungen erhalten.

   Im folgenden Screenshot sehen Sie ein decodiertes Token, das von einer Anwendung mit mehreren Berechtigungen für Microsoft Defender for Endpoint abgerufen wurde:

   

   Der Anspruch "tid" ist die Mandanten-ID, zu der das Token gehört.

Verwenden des Tokens für den Zugriff auf Microsoft Defender for Endpoint-API

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

2. Legen Sie den Autorisierungsheader in der HTTP-Anforderung fest, an Bearer {token} die Sie senden (Bearer ist das Autorisierungsschema). Die Ablaufzeit des Tokens beträgt eine Stunde (Sie können mehr als eine Anforderung mit demselben Token senden).

   Hier sehen 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 for Endpoint im Namen eines Benutzers

Tipp

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