Použití rozhraní API Microsoft Defender for Endpoint

Článek
04/26/2024

Platí pro:

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 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í:

api-us.securitycenter.microsoft.com
api-eu.securitycenter.microsoft.com
api-uk.securitycenter.microsoft.com
api-au.securitycenter.microsoft.com

Tato stránka popisuje, jak vytvořit aplikaci pro získání programového přístupu k Defenderu for Endpoint jménem uživatele.

Pokud potřebujete programový přístup Microsoft Defender for Endpoint bez uživatele, přečtěte si téma Access Microsoft Defender for Endpoint s kontextem aplikace.

Pokud si nejste jistí, jaký přístup potřebujete, přečtěte si úvodní stránku.

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 vám umožní automatizovat pracovní toky a inovovat na základě Microsoft Defender for Endpoint 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:

Create aplikace Microsoft Entra
Získání přístupového tokenu pomocí této aplikace
Použití tokenu pro přístup k rozhraní DEFENDER for Endpoint API

Tato stránka vysvětluje, jak vytvořit aplikaci Microsoft Entra, získat přístupový token pro Microsoft Defender for Endpoint a ověřit token.

Poznámka

Při přístupu k rozhraní MICROSOFT DEFENDER FOR ENDPOINT API jménem uživatele budete potřebovat správné oprávnění aplikace a oprávnění uživatele. Pokud nejste obeznámeni s uživatelskými oprávněními na Microsoft Defender for Endpoint, přečtěte si téma Správa přístupu k portálu pomocí řízení přístupu na základě role.

Tip

Pokud máte oprávnění k provedení akce na portálu, máte oprávnění k provedení akce v rozhraní API.

Create aplikace

Přihlaste se k Azure pomocí uživatelského účtu, který má roli globálního správce .
Přejděte na Microsoft Entra ID>Registrace aplikací>Nová registrace.

Když se zobrazí stránka Zaregistrovat aplikaci , zadejte informace o registraci vaší aplikace:

Název – zadejte smysluplný název aplikace, který se zobrazí uživatelům aplikace.

Podporované typy účtů – Vyberte, které účty má vaše aplikace podporovat.

Podporované typy účtů	Popis
Pouze účty v tomto organizačním adresáři	Tuto možnost vyberte, pokud vytváříte obchodní aplikaci. Tato možnost není dostupná, pokud aplikaci neregistrujete v adresáři. Tato možnost se mapuje na Microsoft Entra pouze pro jednoho tenanta. Toto je výchozí možnost, pokud aplikaci neregistrujete mimo adresář. V případech, kdy je aplikace zaregistrovaná mimo adresář, je výchozí Microsoft Entra víceklientského účtu a osobních účtů Microsoft.
Účty v libovolném organizačním adresáři	Tuto možnost vyberte, pokud chcete cílit na všechny firemní a vzdělávací zákazníky. Tato možnost se mapuje na Microsoft Entra pouze s více tenanty. Pokud jste aplikaci zaregistrovali jako Microsoft Entra pouze s jedním tenantem, můžete ji aktualizovat tak, aby se Microsoft Entra více tenantů a vrátila se k jednomu tenantovi prostřednictvím okna Ověřování.
Účty v libovolném organizačním adresáři a osobních účtech Microsoft	Tuto možnost vyberte, pokud chcete cílit na nejširší skupinu zákazníků. Tato možnost se mapuje na Microsoft Entra účtů Microsoft s více tenanty a osobními účty. Pokud jste aplikaci zaregistrovali jako Microsoft Entra účtů Microsoft s více tenanty a osobními účty, nemůžete to v uživatelském rozhraní změnit. Místo toho musíte ke změně podporovaných typů účtů použít editor manifestu aplikace.

Podporované typy účtů

Popis

Pouze účty v tomto organizačním adresáři

Tuto možnost vyberte, pokud vytváříte obchodní aplikaci. Tato možnost není dostupná, pokud aplikaci neregistrujete v adresáři.

Tato možnost se mapuje na Microsoft Entra pouze pro jednoho tenanta.

Toto je výchozí možnost, pokud aplikaci neregistrujete mimo adresář. V případech, kdy je aplikace zaregistrovaná mimo adresář, je výchozí Microsoft Entra víceklientského účtu a osobních účtů Microsoft.

Účty v libovolném organizačním adresáři

Tuto možnost vyberte, pokud chcete cílit na všechny firemní a vzdělávací zákazníky.

Tato možnost se mapuje na Microsoft Entra pouze s více tenanty.

Pokud jste aplikaci zaregistrovali jako Microsoft Entra pouze s jedním tenantem, můžete ji aktualizovat tak, aby se Microsoft Entra více tenantů a vrátila se k jednomu tenantovi prostřednictvím okna Ověřování.

Účty v libovolném organizačním adresáři a osobních účtech Microsoft

Tuto možnost vyberte, pokud chcete cílit na nejširší skupinu zákazníků.

Tato možnost se mapuje na Microsoft Entra účtů Microsoft s více tenanty a osobními účty.

Pokud jste aplikaci zaregistrovali jako Microsoft Entra účtů Microsoft s více tenanty a osobními účty, nemůžete to v uživatelském rozhraní změnit. Místo toho musíte ke změně podporovaných typů účtů použít editor manifestu aplikace.

Identifikátor URI přesměrování (volitelné) – Vyberte typ aplikace, kterou vytváříte, webového nebo veřejného klienta (mobilní & desktop) a pak zadejte identifikátor URI přesměrování (nebo adresu URL odpovědi) pro vaši aplikaci.
- Pro webové aplikace zadejte základní adresu URL vaší aplikace. Může to http://localhost:31544 být například adresa URL webové aplikace spuštěné na místním počítači. Uživatelé by tuto adresu URL použili k přihlášení k webové klientské aplikaci.
- U veřejných klientských aplikací zadejte identifikátor URI, který Microsoft Entra ID používá k vrácení odpovědí na tokeny. Zadejte hodnotu specifickou pro vaši aplikaci, například myapp://auth.
Konkrétní příklady pro webové aplikace nebo nativní aplikace najdete v našich rychlých startech.

Po dokončení vyberte Zaregistrovat.

Povolte aplikaci přístup k Microsoft Defender for Endpoint a přiřaďte jí oprávnění Číst upozornění:
- 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.
  
  Poznámka
  
  WindowsDefenderATP se nezobrazuje v původním seznamu. Začněte psát jeho název do textového pole, aby se zobrazilo.
- Zvolte Upozornění delegovanýchoprávnění.Číst>> vyberte Přidat oprávnění.
Důležité

Vyberte příslušná oprávnění. Upozornění na čtení jsou jenom příkladem.

Příklady:
- 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 Izolovat oprávnění počítače .
- Pokud chcete zjistit, jaké oprávnění potřebujete, projděte si část Oprávnění v rozhraní API, které chcete volat.
- Vyberte Udělit souhlas.
  
  Poznámka
  
  Pokaždé, když přidáte oprávnění, musíte vybrat možnost Udělit souhlas , aby se nové oprávnění projevilo.
Poznamenejte si ID aplikace a ID tenanta.

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

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

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

Pomocí jazyka C#

Zkopírujte nebo vložte následující třídu do aplikace.

K získání tokenu použijte metodu AcquireUserTokenAsync s ID aplikace, ID tenanta, uživatelským jménem a heslem.

namespace WindowsDefenderATP
{
    using System.Net.Http;
    using System.Text;
    using System.Threading.Tasks;
    using Newtonsoft.Json.Linq;

    public static class WindowsDefenderATPUtils
    {
        private const string Authority = "https://login.microsoftonline.com";

        private const string WdatpResourceId = "https://api.securitycenter.microsoft.com";

        public static async Task<string> AcquireUserTokenAsync(string username, string password, string appId, string tenantId)
        {
            using (var httpClient = new HttpClient())
            {
                var urlEncodedBody = $"resource={WdatpResourceId}&client_id={appId}&grant_type=password&username={username}&password={password}";

                var stringContent = new StringContent(urlEncodedBody, Encoding.UTF8, "application/x-www-form-urlencoded");

                using (var response = await httpClient.PostAsync($"{Authority}/{tenantId}/oauth2/token", stringContent).ConfigureAwait(false))
                {
                    response.EnsureSuccessStatusCode();

                    var json = await response.Content.ReadAsStringAsync().ConfigureAwait(false);

                    var jObject = JObject.Parse(json);

                    return jObject["access_token"].Value<string>();
                }
            }
        }
    }
}

Ověření tokenu

Ověřte, že máte správný token:

Zkopírujte/vložte do JWT token, který jste získali v předchozím kroku, abyste ho dekódoval.
Ověřte, že jste získali deklaraci identity scp s požadovanými oprávněními aplikace.
Na následujícím snímku obrazovky vidíte dekódovaný token získaný z aplikace v tomto kurzu:

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

Zvolte rozhraní API, které chcete použít – Podporovaná rozhraní API Microsoft Defender for Endpoint.
Nastavte autorizační hlavičku v požadavku HTTP, který odešlete na "Bearer {token}" (Bearer je autorizační schéma).
Doba vypršení platnosti tokenu je 1 hodina (se stejným tokenem můžete odeslat více než jeden požadavek).

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é

Tip

Chcete se dozvědět více? Engage s komunitou Microsoft Security v naší technické komunitě: Microsoft Defender for Endpoint Tech Community.