Přístup k rozhraní API Microsoft Defender for Cloud Apps s kontextem uživatele

Článek
11/28/2024

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

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

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

Microsoft Defender for Cloud Apps zpřístupňuje většinu svých dat a akcí prostřednictvím sady programových rozhraní API. Tato rozhraní API umožňují automatizovat pracovní toky a inovovat na základě Microsoft Defender for Cloud Apps 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ření aplikace Microsoft Entra
Získání přístupového tokenu pomocí této aplikace
Použití tokenu pro přístup k rozhraní API Defender for Cloud Apps

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

Poznámka

Při přístupu k rozhraní Microsoft Defender for Cloud Apps API jménem uživatele budete potřebovat správné oprávnění aplikace a oprávnění uživatele. Pokud nemáte zkušenosti s uživatelskými oprávněními pro Microsoft Defender for Cloud Apps, přečtěte si téma Správa přístupu správce.

Tip

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

Vytvoření aplikace

V Centrum pro správu Microsoft Entra zaregistrujte novou aplikaci. Další informace najdete v tématu Rychlý start: Registrace aplikace pomocí Centrum pro správu Microsoft Entra.

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ých 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 pro jednoho tenanta, můžete ji aktualizovat tak, aby byla Microsoft Entra více tenantů a zpět na jednoho tenanta prostřednictvím podokna 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 víceklientských a osobních účtů Microsoft. Pokud jste aplikaci zaregistrovali jako Microsoft Entra víceklientských a osobních účtů Microsoft, 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, **Web 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 Cloud Apps a přiřaďte jí oprávnění Číst upozornění:
- Na stránce aplikace vyberte Oprávnění> rozhraní API Přidat rozhraní APIoprávnění>, kterámoje organizace používá>, zadejte Microsoft Cloud App Security a pak vyberte Microsoft Cloud App Security.
- Poznámka: Microsoft Cloud App Security se nezobrazuje v původním seznamu. Začněte psát jeho název do textového pole, aby se zobrazilo. Nezapomeňte zadat tento název, i když se teď produkt nazývá Defender for Cloud Apps.
- Zvolte Šetření delegovanýchoprávnění.Číst>> vyberte Přidat oprávnění.
- Důležitá poznámka: Vyberte příslušná oprávnění. Investigation.Read je jenom příklad. Další obory oprávnění najdete v tématu Podporované obory oprávnění.
  - 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 správce.
  
  Poznámka: Pokaždé, když přidáte oprávnění, musíte vybrat Udělit souhlas správce , 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:

Podporované obory oprávnění

Název oprávnění	Popis	Podporované akce
Investigation.read	Proveďte všechny podporované akce s aktivitami a výstrahami s výjimkou uzavíracích výstrah. Umožňuje zobrazit rozsahy IP adres, ale nepřidávejte, neaktualizujete ani neodstraňovat. Proveďte všechny akce entit.	Seznam aktivit, načtení, zpětná vazba Seznam upozornění, načtení, označení jako přečtené/nepřečtené Seznam entit, načtení, strom načtení Seznam podsítí
Investigation.manage	Kromě správy výstrah a rozsahů IP adres proveďte všechny akce investigation.read.	Seznam aktivit, načtení, zpětná vazba Seznam upozornění, načtení, označení jako přečtené/nepřečtené, zavření Seznam entit, načtení, strom načtení Seznam podsítí, vytvoření, aktualizace nebo odstranění
Discovery.read	Proveďte všechny podporované akce s aktivitami a výstrahami s výjimkou uzavíracích výstrah. Vypište sestavy a kategorie zjišťování.	Seznam upozornění, načtení, označení jako přečtené/nepřečtené Sestavy seznamu zjišťování, seznam kategorií sestav
Discovery.manage	Oprávnění Discovery.read Zavření upozornění, nahrání souborů zjišťování a generování blokovacích skriptů	Seznam upozornění, načtení, označení jako přečtené/nepřečtené, zavření Sestavy seznamu zjišťování, seznam kategorií sestav Nahrání souboru zjišťování, vygenerování blokového skriptu
Settings.read	Vypíše rozsahy IP adres.	Seznam podsítí
Settings.manage	Výpis a správa rozsahů IP adres	Seznam podsítí, vytvoření, aktualizace nebo odstranění

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

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

Pomocí jazyka C#

Zkopírujte nebo vložte do aplikace následující třídu.
Použijte metodu AcquireUserTokenAsync s ID vaší aplikace, ID tenanta a ověřováním získáte token.

Poznámka

I když následující ukázka kódu ukazuje, jak získat token pomocí toku uživatelského jména a hesla, Microsoft doporučuje používat bezpečnější toky ověřování v produkčním prostředí.

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

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

        private const string MDAId = "05a65629-4c1b-48c1-a78b-804c4abdd4af";
        private const string Scope = "Investigation.read";

        public static async Task<string> AcquireUserTokenAsync(string username, string password, string appId, string tenantId)
        {
            using (var httpClient = new HttpClient())
            {
                var urlEncodedBody = $"scope={MDAId}/{Scope}&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 mohli dekódovat.
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 Cloud Apps

Zvolte rozhraní API, které chcete použít. Další informace najdete v tématu Defender for Cloud Apps API.
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ž jednu žádost).

Příklad odeslání žádosti o získání seznamu výstrah pomocí jazyka C#

var httpClient = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Get, "https://portal.cloudappsecurity.com/cas/api/v1/alerts/");

request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

var response = httpClient.SendAsync(request).GetAwaiter().GetResult();

// Do something useful with the response

Sdílet prostřednictvím