Přístup partnerů prostřednictvím rozhraní API Microsoft Defender for Endpoint
Platí pro:
- Plán 1 pro Microsoft Defender for Endpoint
- Plán 2 pro Microsoft Defender pro koncový bod
- Microsoft Defender pro firmy
Důležité
Možnosti rozšířeného proaktivního vyhledávání nejsou součástí Defender pro firmy.
Chcete vyzkoušet Defender pro Endpoint? Zaregistrujte se a získejte bezplatnou zkušební verzi,
Poznámka
Pokud jste zákazníkem státní správy USA, použijte identifikátory URI uvedené v Microsoft Defender for Endpoint pro zákazníky státní správy USA.
Tip
Pro lepší výkon můžete použít server blíže k vašemu geografickému umístění:
- 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
- ina.api.security.microsoft.com
Tato stránka popisuje, jak vytvořit aplikaci Microsoft Entra pro získání programového přístupu k Microsoft Defender for Endpoint jménem vašich zákazníků.
Microsoft Defender for Endpoint 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í toky a inovovat na základě Microsoft Defender for Endpoint funkcí. 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 pokud chcete rozhraní API používat, musíte provést následující kroky:
Vytvořte aplikaci Microsoft Entra s více tenanty.
Získejte od správce zákazníka autorizaci (souhlas) pro přístup k prostředkům Defenderu for Endpoint, 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 for Endpoint.
Následující postup vás provede vytvořením aplikace Microsoft Entra, získáním přístupového tokenu pro Microsoft Defender for Endpoint a ověřením tokenu.
Důležité
Microsoft doporučuje používat role s co nejmenším počtem oprávnění. To pomáhá zlepšit zabezpečení vaší organizace. Globální správce je vysoce privilegovaná role, která by měla být omezená na nouzové scénáře, když nemůžete použít existující roli.
Přihlaste se ke svému tenantovi Azure.
Přejděte na Microsoft Entra ID>Registrace aplikací>Nová registrace.
V registračním formuláři:
Zvolte název aplikace.
Podporované typy účtů – účty v libovolném organizačním adresáři.
Identifikátor URI přesměrování – typ: Web, URI: https://portal.azure.com
Povolte aplikaci přístup k Microsoft Defender for Endpoint a přiřaďte ji s minimální sadou oprávnění vyžadovanou k dokončení integrace.
Pokud chcete zjistit, jaké oprávnění potřebujete, projděte si část Oprávnění v rozhraní API, které chcete volat. Například:
- Pokud chcete spouštět rozšířené dotazy, vyberte oprávnění Ke spouštění rozšířených dotazů .
- Pokud chcete izolovat zařízení, vyberte oprávnění Izolovat počítač .
V následujícím příkladu použijeme oprávnění Číst všechny výstrahy :
Zvolte Oprávnění> aplikaceAlert.Read.All> vyberte v části Přidat oprávnění.
Vyberte Udělit souhlas.
- Pokaždé, když přidáte oprávnění, musíte vybrat možnost Udělit souhlas , aby se nové oprávnění projevilo.
Přidejte do aplikace tajný kód.
- Vyberte Certifikáty & tajných kódů, přidejte popis tajného kódu a vyberte Přidat.
Po výběru možnosti Přidat nezapomeňte zkopírovat vygenerovanou hodnotu tajného kódu. Po odchodu ho nebudete moct načíst!
Poznamenejte si ID aplikace:
Přidejte aplikaci do tenanta zákazníka.
Potřebujete, aby vaše aplikace byla schválená v každém tenantovi zákazníka, ve kterém ji chcete používat. Toto schválení je nezbytné, protože vaše aplikace komunikuje s Microsoft Defender for Endpoint aplikací jménem zákazníka.
Uživatelský účet s odpovídajícími oprávněními pro tenanta zákazníka musí vybrat odkaz pro vyjádření souhlasu a schválit vaši aplikaci.
Odkaz pro vyjádření souhlasu je ve formátu:
https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true
Kde
00000000-0000-0000-0000-000000000000
by mělo být nahrazeno vaším ID aplikace.Po výběru odkazu pro vyjádření souhlasu se přihlaste k tenantovi zákazníka a pak udělte souhlas pro aplikaci.
Kromě toho budete muset zákazníka požádat o ID tenanta a uložit ho pro budoucí použití při získání tokenu.
Hotovo! Úspěšně jste zaregistrovali aplikaci! Informace o získání a ověření tokenu najdete v následujících příkladech.
Pokud chcete získat přístupový token jménem zákazníka, použijte ID tenanta zákazníka při následujících získání tokenů.
Další informace o tokenu Microsoft Entra najdete v Microsoft Entra kurzu.
# 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
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. Pokud chcete upgradovat, projděte si průvodce migrací.
Vytvořte novou konzolovou aplikaci.
Nainstalujte NuGet Microsoft.Identity.Client.
Pomocí kódu přidejte následující kód:
using Microsoft.Identity.Client;
Tento kód byl testován pomocí NuGetu
Microsoft.Identity.Client
.Zkopírujte a vložte do aplikace následující kód (nezapomeňte aktualizovat tři proměnné:
tenantId
,appId
aappSecret
).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;
Viz Získání tokenu pomocí Pythonu.
Poznámka
Následující postup, který se předpokládá Curl pro Windows je již nainstalován na vašem počítači
Otevřete příkazové okno.
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 for Endpoint aplikaci.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
Získáte odpověď, která se podobá následujícímu fragmentu kódu:
{"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn <truncated> aWReH7P0s0tjTBX8wGWqJUdDA"}
Potvrďte, že jste obdrželi správný token.
Zkopírujte nebo vložte do JWT token, který jste získali v předchozím kroku, abyste ho dekódovat.
Ověřte, že získáte deklaraci identity rolí s příslušnými oprávněními.
Na následujícím snímku obrazovky vidíte dekódovaný token získaný z aplikace s více oprávněními k Microsoft Defender for Endpoint:
Deklarace identity "tid" je ID tenanta, ke které token patří.
Zvolte rozhraní API, které chcete použít. Další informace najdete v tématu Podporovaná rozhraní API Microsoft Defender for Endpoint.
Nastavte autorizační hlavičku v požadavku HTTP, který odešlete do
Bearer {token}
(Bearer je autorizační schéma). Doba vypršení platnosti tokenu je jedna hodina (se stejným tokenem můžete odeslat více než jednu žádost).Tady je příklad odeslání žádosti o získání seznamu upozornění pomocí jazyka 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
- Podporovaná rozhraní API aplikace Microsoft Defender for Endpoint
- Přístup k Microsoft Defender for Endpoint jménem uživatele
Tip
Chcete se dozvědět více? Engage s komunitou Microsoft Security v naší technické komunitě: Microsoft Defender for Endpoint Tech Community.