Vytvoření aplikace pro přístup k Microsoft Defender XDR bez uživatele
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 Vytvoření aplikace pro přístup k rozhraním API Microsoft Defender XDR jménem uživatele a Vytvoření aplikace s přístupem partnera k rozhraním API pro Microsoft Defender XDR. 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.
Tento článek vysvětluje, jak:
- Vytvoření aplikace Microsoft Entra
- Získání přístupového tokenu pro Microsoft Defender XDR
- Ověřte token.
Přihlaste se k Azure.
Přejděte na Microsoft Entra ID>Registrace aplikací>Nová registrace.
Ve formuláři zvolte název aplikace a pak 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.
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.
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.
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.
# 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
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
: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;
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"]
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 zákazníka, 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://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"}
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.All
aAdvancedHunting.Read.All
:
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();
- přehled rozhraní API Microsoft Defender XDR
- Přístup k rozhraním API Microsoft Defender XDR
- Vytvoření aplikace Hello world
- Vytvoření aplikace pro přístup k rozhraním API Microsoft Defender XDR jménem uživatele
- Vytvoření aplikace s přístupem partnera s více tenanty k rozhraním API Microsoft Defender XDR
- Informace o limitech a licencování rozhraní API
- Vysvětlení kódů chyb
- Správa tajných kódů v serverových aplikacích pomocí Azure Key Vault
- Autorizace OAuth 2.0 pro přihlašování uživatelů a přístup k rozhraní API
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.