Vytvoření aplikace s přístupem partnera k rozhraním API Microsoft Defender XDR

Článek
11/19/2024

Platí pro:

Microsoft Defender XDR

Důležité

Některé informace se týkají předprodeje produktu, který může být před komerčním vydáním podstatně změněn. Společnost Microsoft neposkytuje v souvislosti se zde uvedenými informacemi žádné výslovné ani předpokládané záruky.

Tato stránka popisuje, jak vytvořit aplikaci Microsoft Entra, která má programový přístup k Microsoft Defender XDR jménem uživatelů ve více tenantech. Aplikace s více tenanty jsou užitečné pro obsluhu velkých skupin uživatelů.

Pokud potřebujete programový přístup k Microsoft Defender XDR jménem jednoho uživatele, přečtěte si téma Vytvoření aplikace pro přístup k rozhraním API Microsoft Defender XDR jménem uživatele. Pokud potřebujete přístup bez explicitně definovaného uživatele (například pokud píšete aplikaci na pozadí nebo proces démon), přečtěte si téma Vytvoření aplikace pro přístup k Microsoft Defender XDR bez uživatele. Pokud si nejste jistí, jaký druh přístupu potřebujete, přečtěte si téma Začínáme.

Microsoft Defender XDR zveřejňuje většinu svých dat a akcí prostřednictvím sady programových rozhraní API. Tato rozhraní API pomáhají automatizovat pracovní postupy a využívat možnosti Microsoft Defender XDR. Tento přístup rozhraní API vyžaduje ověřování OAuth 2.0. Další informace najdete v tématu Tok autorizačního kódu OAuth 2.0.

Obecně platí, že k použití těchto rozhraní API budete muset provést následující kroky:

Vytvořte aplikaci Microsoft Entra.
Získání přístupového tokenu pomocí této aplikace
Token použijte pro přístup k rozhraní API Microsoft Defender XDR.

Vzhledem k tomu, že tato aplikace má více tenantů, budete také potřebovat souhlas správce od každého tenanta jménem jeho uživatelů.

Tento článek vysvětluje, jak:

Vytvoření aplikace Microsoft Entra s více tenanty
Získejte od správce uživatele autorizovaný souhlas s přístupem k Microsoft Defender XDR prostředků, které potřebuje.
Získání přístupového tokenu pro Microsoft Defender XDR
Ověření tokenu

Microsoft Defender XDR zveřejňuje většinu svých dat a akcí prostřednictvím sady programových rozhraní API. Tato rozhraní API vám pomohou automatizovat pracovní toky a inovovat na základě Microsoft Defender XDR schopností. Přístup k rozhraní API vyžaduje ověřování OAuth 2.0. Další informace najdete v tématu Tok autorizačního kódu OAuth 2.0.

Obecně platí, že abyste mohli rozhraní API používat, budete muset provést následující kroky:

Vytvořte aplikaci Microsoft Entra s více tenanty.
Získejte od správce uživatele autorizaci (souhlas) pro přístup k Microsoft Defender XDR prostředkům, které potřebuje.
Získání přístupového tokenu pomocí této aplikace
Token použijte pro přístup k rozhraní API Microsoft Defender XDR.

Následující kroky vám pomůžou vytvořit aplikaci s více tenanty Microsoft Entra, získat přístupový token pro Microsoft Defender XDR a ověřit ho.

Vytvoření aplikace pro více tenantů

Přihlaste se k Azure.
Přejděte na Microsoft Entra ID>Registrace aplikací>Nová registrace.
V registračním formuláři:
- Zvolte název aplikace.
- V části Podporované typy účtů vyberte Účty v libovolném organizačním adresáři (libovolný Microsoft Entra adresář) – víceklient.
- Vyplňte část Identifikátor URI přesměrování . Vyberte typ Web a jako identifikátor URI https://portal.azure.compro přesměrování zadejte .
Po vyplnění formuláře vyberte Zaregistrovat.
Na stránce aplikace vyberte Oprávnění> rozhraní API Přidat rozhraní APIoprávnění>, kterápoužívá> moje organizace, zadejte Microsoft Threat Protection a vyberte Microsoft Threat Protection. Vaše aplikace teď má přístup k Microsoft Defender XDR.

Tip

Microsoft Threat Protection je dřívější název Microsoft Defender XDR a nezobrazí se v původním seznamu. Aby se zobrazilo, musíte začít psát jeho název do textového pole.
Vyberte Oprávnění aplikace. Zvolte příslušná oprávnění pro váš scénář (například Incident.Read.All) a pak vyberte Přidat oprávnění.

Poznámka

Musíte vybrat příslušná oprávnění pro váš scénář. Čtení všech incidentů je jenom příklad. Pokud chcete zjistit, jaké oprávnění potřebujete, projděte si část Oprávnění v rozhraní API, které chcete volat.

Pokud například chcete spouštět rozšířené dotazy, vyberte oprávnění Spustit rozšířené dotazy. Pokud chcete izolovat zařízení, vyberte oprávnění Izolovat počítač.
Vyberte Udělit souhlas správce. Pokaždé, když přidáte oprávnění, musíte vybrat Udělit souhlas správce , aby se toto oprávnění projevilo.
Pokud chcete do aplikace přidat tajný kód, vyberte Certifikáty & tajných kódů, přidejte popis tajného kódu a pak vyberte Přidat.

Tip

Po výběru možnosti Přidat vyberte zkopírování vygenerované hodnoty tajného kódu. Jakmile odejdete, nebudete moct načíst hodnotu tajného kódu.
Poznamenejte si ID aplikace a ID tenanta na bezpečném místu. Jsou uvedené v části Přehled na stránce vaší aplikace.
Přidejte aplikaci do tenanta uživatele.

Vzhledem k tomu, že vaše aplikace komunikuje s Microsoft Defender XDR jménem vašich uživatelů, musí být schválená pro každého tenanta, ve kterém ji chcete používat.

Správce z tenanta vašeho uživatele musí zobrazit odkaz pro vyjádření souhlasu a schválit vaši aplikaci.

Odkaz pro vyjádření souhlasu má tvar:
```
https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true
```
Číslice by měly být nahrazeny 00000000-0000-0000-0000-000000000000 VAŠÍM ID aplikace.

Po kliknutí na odkaz pro vyjádření souhlasu se přihlaste jako správce tenanta uživatele a udělte souhlas s aplikací.

Budete také muset požádat uživatele o ID tenanta. ID tenanta je jedním z identifikátorů používaných k získání přístupových tokenů.

Hotovo! Úspěšně jste zaregistrovali aplikaci!
V následujících příkladech najdete informace o získání a ověření tokenu.

Získání přístupového tokenu

Další informace o tokenech Microsoft Entra najdete v kurzu Microsoft Entra.

Důležité

I když příklady v této části podporují vkládání tajných kódů pro účely testování, nikdy byste tajné kódy neměli pevně zakódovat do aplikace spuštěné v produkčním prostředí. Třetí strana může použít váš tajný kód pro přístup k prostředkům. Tajné kódy aplikace můžete zabezpečit pomocí Azure Key Vault. Praktický příklad ochrany aplikace najdete v tématu Správa tajných kódů v serverových aplikacích pomocí Azure Key Vault.

Tip

V následujících příkladech použijte ID tenanta uživatele k otestování, že skript funguje.

Získání přístupového tokenu pomocí PowerShellu

# This code gets the application context token and saves it to a file named "Latest-token.txt" under the current directory.

$tenantId = '' # Paste your directory (tenant) ID here
$clientId = '' # Paste your application (client) ID here
$appSecret = '' # Paste your own app secret here to test, then store it in a safe place!

$resourceAppIdUri = 'https://api.security.microsoft.com'
$oAuthUri = "https://login.windows.net/$tenantId/oauth2/token"

$authBody = [Ordered] @{
    resource = $resourceAppIdUri
    client_id = $clientId
    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

Získání přístupového tokenu pomocí jazyka C#

Poznámka

Následující kód byl testován s NuGet Microsoft.Identity.Client 3.19.8.

Důležité

Balíček NuGet Microsoft.IdentityModel.Clients.ActiveDirectory a knihovna Azure AD Authentication Library (ADAL) jsou zastaralé. Od 30. června 2020 nebyly přidány žádné nové funkce. Důrazně doporučujeme provést upgrade. Další podrobnosti najdete v průvodci migrací .

Vytvořte novou konzolovou aplikaci.
Nainstalujte NuGet Microsoft.Identity.Client.
Přidejte následující řádek:
```
using Microsoft.Identity.Client;
```

Zkopírujte a vložte do aplikace následující kód (nezapomeňte aktualizovat tři proměnné: tenantId, clientId, ), 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;

Získání přístupového tokenu pomocí Pythonu

import json
import urllib.request
import urllib.parse

tenantId = '' # Paste your directory (tenant) ID here
clientId = '' # Paste your application (client) ID here
appSecret = '' # Paste your own app secret here to test, then store it in a safe place, such as the Azure Key Vault!

url = "https://login.windows.net/%s/oauth2/token" % (tenantId)

resourceAppIdUri = 'https://api.security.microsoft.com'

body = {
    'resource' : resourceAppIdUri,
    'client_id' : clientId,
    'client_secret' : appSecret,
    'grant_type' : 'client_credentials'
}

data = urllib.parse.urlencode(body).encode("utf-8")

req = urllib.request.Request(url, data)
response = urllib.request.urlopen(req)
jsonResponse = json.loads(response.read())
aadToken = jsonResponse["access_token"]

Získání přístupového tokenu pomocí curl

Poznámka

Curl je předinstalovaný na Windows 10 verze 1803 a novější. V případě jiných verzí Windows si stáhněte a nainstalujte nástroj přímo z oficiálního webu curl.

Otevřete příkazový řádek a nastavte CLIENT_ID na ID aplikace Azure.
Nastavte CLIENT_SECRET na tajný kód aplikace Azure.
Nastavte TENANT_ID na ID tenanta Azure uživatele, který chce používat vaši aplikaci pro přístup k Microsoft Defender XDR.
Spusťte následující příkaz:

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

Úspěšná odpověď bude vypadat takto:

{"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn <truncated> aWReH7P0s0tjTBX8wGWqJUdDA"}

Ověření tokenu

Zkopírujte token a vložte ho na web validátoru webových tokenů JSON , JWT, aby se dekóduje.
Ujistěte se, že deklarace identity rolí v dekódovaném tokenu obsahuje požadovaná oprávnění.

Na následujícím obrázku vidíte dekódovaný token získaný z aplikace s oprávněními Incidents.Read.All, Incidents.ReadWrite.Alla AdvancedHunting.Read.All :

Použití tokenu pro přístup k rozhraní API Microsoft Defender XDR

Zvolte rozhraní API, které chcete použít (incidenty nebo rozšířené proaktivní vyhledávání). Další informace najdete v tématu Podporovaná rozhraní MICROSOFT DEFENDER XDR API.
V požadavku HTTP, který se chystáte odeslat, nastavte autorizační hlavičku na "Bearer" <token>, Bearer je autorizační schéma a token je váš ověřený token.
Platnost tokenu vyprší do jedné hodiny. Během této doby můžete odeslat více než jednu žádost se stejným tokenem.

Následující příklad ukazuje, jak odeslat žádost o získání seznamu incidentů pomocí jazyka C#.

   var httpClient = new HttpClient();
   var request = new HttpRequestMessage(HttpMethod.Get, "https://api.security.microsoft.com/api/incidents");

   request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

   var response = httpClient.SendAsync(request).GetAwaiter().GetResult();

Tip

Chcete se dozvědět více? Spojte se s komunitou zabezpečení společnosti Microsoft v naší technické komunitě: Technická komunita Microsoft Defender XDR.

Sdílet prostřednictvím

Vytvoření aplikace s přístupem partnera k rozhraním API Microsoft Defender XDR

Vytvoření aplikace pro více tenantů

Získání přístupového tokenu

Získání přístupového tokenu pomocí PowerShellu

Získání přístupového tokenu pomocí jazyka C#

Získání přístupového tokenu pomocí Pythonu

Získání přístupového tokenu pomocí curl

Ověření tokenu

Použití tokenu pro přístup k rozhraní API Microsoft Defender XDR

Váš názor

Další materiály

Sdílet prostřednictvím

Vytvoření aplikace s přístupem partnera k rozhraním API Microsoft Defender XDR

Vytvoření aplikace pro více tenantů

Získání přístupového tokenu

Získání přístupového tokenu pomocí PowerShellu

Získání přístupového tokenu pomocí jazyka C#

Získání přístupového tokenu pomocí Pythonu

Získání přístupového tokenu pomocí curl

Ověření tokenu

Použití tokenu pro přístup k rozhraní API Microsoft Defender XDR

Související články

Váš názor

Další materiály