Přístup partnerů prostřednictvím rozhraní API programu 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é

Rozšířené možnosti proaktivního vyhledávání nejsou součástí Defenderu 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 programu 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 Defenderu 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ě funkcí Microsoft Defenderu for Endpoint. 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:

1. Vytvořte aplikaci Microsoft Entra s více tenanty.

2. Získejte od správce zákazníka autorizaci (souhlas) pro přístup k prostředkům Defenderu for Endpoint, které potřebuje.

3. Získání přístupového tokenu pomocí této aplikace

4. Token použijte pro přístup k rozhraní API Microsoft Defenderu 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.

Vytvoření víceklientských aplikací

1. Přihlaste se ke svému tenantovi Azure pomocí uživatele, který má roli globálního správce .

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

   

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

     

4. Povolte aplikaci přístup k Microsoft Defenderu for Endpoint a přiřaďte ji s minimální sadou oprávnění vyžadovanou k dokončení integrace.

   • Na stránce vaší aplikace vyberte Oprávnění> rozhraní APIPřidatrozhraní API oprávnění>, která moje organizace používá>, zadejte WindowsDefenderATP a vyberte WindowsDefenderATP.

   • WindowsDefenderATP se nezobrazuje v původním seznamu. Začněte psát jeho název do textového pole, aby se zobrazilo.

     

Vyžádání oprávnění rozhraní API

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 :

1. Zvolte Oprávnění> aplikaceAlert.Read.All> vyberte v části Přidat oprávnění.

   

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

   

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

   

4. Poznamenejte si ID aplikace:

   • Na stránce aplikace přejděte na Přehled a zkopírujte následující informace:

     

5. 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 aplikací Microsoft Defender for Endpoint jménem zákazníka.

   Uživatel s globálním správcem z tenanta zákazníka musí vybrat 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
   

   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 jako globální správce tenanta zákazníka a odsouhlaste 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.

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

Příklad získání přístupového tokenu

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 kurzu Microsoft Entra.

Použití PowerShellu

# 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

Pomocí jazyka C#

Důležité

Balíček NuGet Microsoft.IdentityModel.Clients.ActiveDirectory a knihovna ADAL (Azure AD Authentication Library) jsou zastaralé. Od 30. června 2020 nebyly přidány žádné nové funkce. Pokud chcete upgradovat, projděte si průvodce migrací.

1. Vytvořte novou konzolovou aplikaci.

2. Nainstalujte NuGet Microsoft.Identity.Client.

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

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

Použití Pythonu

Viz Získání tokenu pomocí Pythonu.

Použití aplikace Curl

Poznámka

Následující postup, který se předpokládá Curl pro Windows je již nainstalován na vašem počítači

1. Otevřete příkazové okno.

2. Nastavte CLIENT_ID na ID aplikace Azure.

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

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

5. 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"}
   

Ověření tokenu

Potvrďte, že jste obdrželi správný token.

1. Zkopírujte nebo vložte do JWT token, který jste získali v předchozím kroku, abyste ho dekódovat.

2. 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 Defenderu for Endpoint:

   

   Deklarace identity "tid" je ID tenanta, ke které token patří.

Použití tokenu pro přístup k rozhraní API Microsoft Defenderu for Endpoint

1. Zvolte rozhraní API, které chcete použít. Další informace najdete v tématu Podporovaná rozhraní API programu Microsoft Defender for Endpoint.

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

Viz také

• Podporovaná rozhraní API aplikace Microsoft Defender for Endpoint
• Přístup k Microsoft Defenderu for Endpoint jménem uživatele

Tip

Chcete se dozvědět více? Spojte se s komunitou zabezpečení Microsoftu v naší technické komunitě: Technická komunita Microsoft Defenderu for Endpoint.