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

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

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

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 die Microsoft Defender für Endpunkt-API zuzugreifen.

In den folgenden Schritten erfahren Sie, 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 geringsten Berechtigungen. Dies trägt zur Verbesserung der Sicherheit für Ihre Organisation bei. Globaler Administrator ist eine Rolle mit hohen Berechtigungen, 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 mit einem Benutzer an, der über die Rolle "Globaler Administrator " verfügt.

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. Gewähren Sie Ihrer Anwendung den Zugriff auf Microsoft Defender für Endpunkt, und weisen Sie es mit dem minimalen Berechtigungssatz zu, der zum Abschließen der Integration erforderlich ist.

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

   • 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 der Microsoft Defender für Endpunkt-Anwendung interagiert.

   Ein Benutzer mit einem globalen Administrator aus dem Mandanten Ihres Kunden muss den Zustimmungslink auswählen und Ihre Anwendung genehmigen.

   Der Zustimmungslink hat das folgende Format:

   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 als globaler Administrator des Mandanten des Kunden an, und stimmen Sie der Anwendung zu.

   

   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 zum Microsoft Entra-Token finden Sie im 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 die Azure AD-Authentifizierungsbibliothek (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 die Microsoft Defender für Endpunkt-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 für Endpunkt abgerufen wurde:

   

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

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 Microsoft Defender für Endpunkt-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 für Endpunkt im Namen eines Benutzers

Tipp

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