Create aplikace pro přístup k Microsoft Defender XDR bez uživatele

  • Článek

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 pro získání programového přístupu k Microsoft Defender XDR bez definovaného uživatele – například pokud vytváříte proces démon nebo službu na pozadí.

Pokud potřebujete programový přístup k Microsoft Defender XDR jménem jednoho nebo více uživatelů, přečtěte si téma Create aplikace pro přístup k rozhraním API Microsoft Defender XDR jménem uživatele a Create aplikaci s přístupem partnera k Microsoft Defender XDR Rozhraní API. 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:

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

Tento článek vysvětluje, jak:

  • Create aplikace Microsoft Entra
  • Získání přístupového tokenu pro Microsoft Defender XDR
  • Ověřte token.

Create aplikace

  1. Přihlaste se k Azure jako uživatel s rolí globálního správce .

  2. Přejděte na Microsoft Entra ID>Registrace aplikací>Nová registrace.

    Karta Nová registrace na portálu Microsoft Defender

  3. Ve formuláři zvolte název aplikace a pak vyberte Zaregistrovat.

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

    Karta využití rozhraní API organizace na portálu Microsoft Defender

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

    Podokno oprávnění aplikace na portálu Microsoft Defender

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

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

    Podokno související s udělením souhlasu na portálu Microsoft Defender

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

    Podokno Vytvořit aplikaci na portálu Microsoft Defender

  8. Poznamenejte si ID aplikace a ID tenanta na bezpečném místu. Jsou uvedené v části Přehled na stránce vaší aplikace.

    Podokno Přehled na portálu Microsoft Defender

  9. Pouze pro Microsoft Defender XDR partnery: Postupujte podle těchto pokynů pro přístup partnerů prostřednictvím rozhraní API Microsoft Defender XDR a nastavte aplikaci na více tenantů, aby byla dostupná ve všech tenantech, jakmile obdržíte souhlas správce. Přístup partnerů se vyžaduje pro aplikace třetích stran – například pokud vytvoříte aplikaci, která má běžet ve více tenantech zákazníků. Není to nutné , pokud vytvoříte službu, kterou chcete spustit pouze ve svém tenantovi, například aplikaci pro vlastní použití, která bude pracovat pouze s vašimi daty. Nastavení aplikace na více tenantů:

    • Přejděte na Ověřování a přidejte https://portal.azure.com jako identifikátor URI přesměrování.

    • V dolní části stránky v části Podporované typy účtů vyberte Účty v libovolném organizačním adresáři souhlas aplikace pro vaši aplikaci s více tenanty.

    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.

    Globální správce služby Active Directory pro každého tenanta musí vybrat odkaz pro vyjádření souhlasu a schválit vaši aplikaci.

    Odkaz pro vyjádření souhlasu má následující strukturu:

    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.

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.

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, such as the Azure Key Vault!

$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í .

  1. Create novou konzolovou aplikaci.

  2. Nainstalujte NuGet Microsoft.Identity.Client.

  3. Přidejte následující řádek:

    using Microsoft.Identity.Client;

  4. Zkopírujte a vložte do aplikace následující kód (nezapomeňte aktualizovat tři proměnné: tenantId, clientId, ), appSecret:

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

  1. Otevřete příkazový řádek a nastavte CLIENT_ID na ID aplikace Azure.

  2. Nastavte CLIENT_SECRET na tajný kód aplikace Azure.

  3. Nastavte TENANT_ID na ID tenanta Azure zákazníka, který chce používat vaši aplikaci pro přístup k Microsoft Defender XDR.

  4. 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://api.security.microsoft.com/.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

  1. Zkopírujte token a vložte ho na web validátoru webových tokenů JSON , JWT, aby se dekóduje.

  2. 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 :

    Podokno Dekódovaný token na portálu Microsoft Defender

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

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

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

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