Partnerzugriff über Microsoft Defender for Endpoint-APIs

Artikel
04/27/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 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 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:

Create eine mehrinstanzenfähige Microsoft Entra-Anwendung.
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.
Rufen Sie mithilfe dieser Anwendung ein Zugriffstoken ab.
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.

Create der mehrinstanzenfähigen App

Melden Sie sich bei Ihrem Azure-Mandanten mit einem Benutzer an, der über die Rolle "Globaler Administrator " verfügt.
Navigieren Sie zu Microsoft Entra ID>App-Registrierungen>Neue Registrierung.
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
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.
- Beachten Sie, dass WindowsDefenderATP nicht in der ursprünglichen Liste angezeigt wird. 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:

Wählen Sie zum Ausführen erweiterter Abfragen 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" :

Wählen Sie Anwendungsberechtigungen>Alert.Read.All> unter Berechtigungen hinzufügen aus.
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.
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.
Wichtig: 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!
Notieren Sie sich Ihre Anwendungs-ID:
- Navigieren Sie auf der Anwendungsseite zu Übersicht , und kopieren Sie die folgenden Informationen:
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 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
```
Wobei 000000000-0000-0000-00000-000000000000 durch Ihre Anwendungs-ID ersetzt werden sollte

Nachdem Sie auf den Zustimmungslink geklickt haben, melden Sie sich beim globalen 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.
Fertig. Sie haben erfolgreich eine Bewerbung registriert! In den folgenden Beispielen finden Sie Informationen zum Abrufen und Überprüfen von Token.

Abrufen eines Zugriffstokenbeispiels

Hinweis: 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#

Der folgende Code wurde mit Nuget Microsoft.Identity.Client getestet.

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. Wir empfehlen Ihnen dringend, ein Upgrade durchzuführen. Weitere Informationen finden Sie im Migrationsleitfaden .

Create einer neuen Konsolenanwendung
Installieren von NuGet Microsoft.Identity.Client
Fügen Sie folgendes hinzu, indem Sie
```
using Microsoft.Identity.Client;
```

Kopieren Sie den folgenden Code, und fügen Sie ihn in Ihre Anwendung ein (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 mit Python.

Verwenden von Curl

Hinweis

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

Öffnen Sie ein Befehlsfenster.
Legen Sie CLIENT_ID auf Ihre Azure-Anwendungs-ID fest.
Legen Sie CLIENT_SECRET auf Ihren geheimen Azure-Anwendungsschlüssel fest.
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.

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 des Formulars:

{"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.

Kopieren Sie das Token, das Sie im vorherigen Schritt erhalten haben, und fügen Sie es in JWT ein, um es zu decodieren.
Vergewissern Sie sich, dass Sie den Anspruch "roles" mit den gewünschten 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

Wählen Sie die API aus, die Sie verwenden möchten. Weitere Informationen finden Sie unter Unterstützte 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).

Hier ist 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