Toegang tot Microsoft Defender for Cloud Apps API met gebruikerscontext

2024-11-28

Op deze pagina wordt beschreven hoe u namens een gebruiker een toepassing maakt om programmatische toegang te krijgen tot Defender for Cloud Apps.

Als u programmatische toegang nodig hebt Microsoft Defender for Cloud Apps zonder een gebruiker, raadpleegt u Access Microsoft Defender for Cloud Apps met toepassingscontext.

Als u niet zeker weet welke toegang u nodig hebt, leest u de pagina Inleiding.

Microsoft Defender for Cloud Apps maakt veel van de gegevens en acties beschikbaar via een set programmatische API's. Met deze API's kunt u werkstromen automatiseren en innoveren op basis van Microsoft Defender for Cloud Apps mogelijkheden. Voor de API-toegang is OAuth2.0-verificatie vereist. Zie OAuth 2.0-autorisatiecodestroom voor meer informatie.

Over het algemeen moet u de volgende stappen uitvoeren om de API's te gebruiken:

Een Microsoft Entra-toepassing maken
Een toegangstoken ophalen met behulp van deze toepassing
Het token gebruiken voor toegang tot Defender for Cloud Apps API

Op deze pagina wordt uitgelegd hoe u een Microsoft Entra-toepassing maakt, een toegangstoken opgeeft om te Microsoft Defender for Cloud Apps en het token valideert.

Opmerking

Bij het openen van Microsoft Defender for Cloud Apps API namens een gebruiker, hebt u de juiste toepassingsmachtiging en gebruikersmachtiging nodig. Zie Beheerderstoegang beheren als u niet bekend bent met gebruikersmachtigingen voor Microsoft Defender for Cloud Apps.

Tip

Als u gemachtigd bent om een actie uit te voeren in de portal, hebt u de machtiging om de actie uit te voeren in de API.

Een app maken

Registreer in de Microsoft Entra-beheercentrum een nieuwe toepassing. Zie Quickstart: Een toepassing registreren bij de Microsoft Entra-beheercentrum voor meer informatie.

Wanneer de pagina Een toepassing registreren wordt weergegeven, voert u de registratiegegevens van uw toepassing in:

Naam : voer een betekenisvolle toepassingsnaam in die wordt weergegeven voor gebruikers van de app.

Ondersteunde accounttypen : selecteer welke accounts u wilt ondersteunen door uw toepassing.

Ondersteunde accounttypen	Beschrijving
Alleen accounts in deze organisatiemap	Selecteer deze optie als u een LOB-toepassing (Line-Of-Business) bouwt. Deze optie is niet beschikbaar als u de toepassing niet registreert in een map. Deze optie wordt toegewezen aan Microsoft Entra met één tenant. Dit is de standaardoptie, tenzij u de app buiten een map registreert. In gevallen waarin de app buiten een directory is geregistreerd, is de standaardinstelling Microsoft Entra multitenant- en persoonlijke Microsoft-accounts.
Accounts in elke organisatiemap	Selecteer deze optie als u zich wilt richten op alle zakelijke en educatieve klanten. Deze optie wordt toegewezen aan een Microsoft Entra multitenant. Als u de app hebt geregistreerd als Microsoft Entra-only single-tenant, kunt u deze bijwerken zodat deze wordt Microsoft Entra multitenant en terug naar één tenant via het deelvenster Verificatie.
Accounts in elke organisatiemap en persoonlijke Microsoft-accounts	Selecteer deze optie om zich te richten op de breedste set klanten. Deze optie wordt toegewezen aan Microsoft Entra multitenant en persoonlijke Microsoft-accounts. Als u de app hebt geregistreerd als Microsoft Entra multitenant en persoonlijke Microsoft-accounts, kunt u dit niet wijzigen in de gebruikersinterface. In plaats daarvan moet u de manifesteditor van de toepassing gebruiken om de ondersteunde accounttypen te wijzigen.

Omleidings-URI (optioneel): selecteer het type app dat u bouwt, **Web of Openbare client (mobiel & desktop) en voer vervolgens de omleidings-URI (of antwoord-URL) voor uw toepassing in.
- Geef voor webtoepassingen de basis-URL van uw app op. Dit kan bijvoorbeeld http://localhost:31544 de URL zijn voor een web-app die wordt uitgevoerd op uw lokale computer. Gebruikers gebruiken deze URL om zich aan te melden bij een webclienttoepassing.
- Geef voor openbare clienttoepassingen de URI op die door Microsoft Entra ID wordt gebruikt om tokenantwoorden te retourneren. Voer een waarde in die specifiek is voor uw toepassing, zoals myapp://auth.
Bekijk onze quickstarts voor specifieke voorbeelden voor webtoepassingen of systeemeigen toepassingen.

Wanneer u klaar bent, selecteert u Registreren.

Geef uw toepassing toegang tot Microsoft Defender for Cloud Apps en wijs de machtiging Waarschuwingen lezen toe:
Selecteer op uw toepassingspagina API-machtigingen Machtigings-API's>toevoegen>die mijn organisatie gebruikt>, typ Microsoft Cloud App Security en selecteer vervolgens Microsoft Cloud App Security.

Opmerking

Microsoft Cloud App Security wordt niet weergegeven in de oorspronkelijke lijst. Begin met het schrijven van de naam in het tekstvak om deze weer te geven. Zorg ervoor dat u deze naam typt, ook al heet het product nu Defender for Cloud Apps.
Kies Gedelegeerde machtigingen>Onderzoek.Lees> selecteer Machtigingen toevoegen

Opmerking

Selecteer de relevante machtigingen. Investigation.Read is slechts een voorbeeld. Zie Ondersteunde machtigingsbereiken voor andere machtigingsbereiken
Als u wilt bepalen welke machtiging u nodig hebt, bekijkt u de sectie Machtigingen in de API die u wilt aanroepen.
Selecteer Beheerderstoestemming verlenen

Opmerking

Telkens wanneer u een machtiging toevoegt, moet u Beheerderstoestemming verlenen selecteren om de nieuwe machtiging van kracht te laten worden.
Noteer uw toepassings-id en uw tenant-id.
Ga op de toepassingspagina naar Overzicht en kopieer de volgende informatie:

Ondersteunde machtigingsbereiken

Machtigingsnaam	Beschrijving	Ondersteunde acties
Investigation.read	Alle ondersteunde acties uitvoeren voor activiteiten en waarschuwingen, behalve waarschuwingen voor sluiten. IP-bereiken weergeven, maar niet toevoegen, bijwerken of verwijderen. Alle entiteitenacties uitvoeren.	Activiteitenlijst, ophalen, feedback Lijst met waarschuwingen, ophalen, markeren als gelezen/ongelezen Entiteitenlijst, ophalen, structuur ophalen Subnetlijst
Investigation.manage	Voer alle investigation.read-acties uit naast het beheren van waarschuwingen en IP-bereiken.	Activiteitenlijst, ophalen, feedback Lijst met waarschuwingen, ophalen, markeren als gelezen/ongelezen, sluiten Entiteitenlijst, ophalen, structuur ophalen Subnetlijst, maken/bijwerken/verwijderen
Discovery.read	Alle ondersteunde acties uitvoeren voor activiteiten en waarschuwingen, behalve waarschuwingen voor sluiten. Detectierapporten en categorieën weergeven.	Lijst met waarschuwingen, ophalen, markeren als gelezen/ongelezen Detectielijstrapporten, lijstrapportcategorieën
Discovery.manage	Discovery.read-machtigingen Waarschuwingen sluiten, detectiebestanden uploaden en blokscripts genereren	Lijst met waarschuwingen, ophalen, markeren als gelezen/ongelezen, sluiten Detectielijstrapporten, lijstrapportcategorieën Detectiebestand uploaden, blokscript genereren
Instellingen.read	IP-bereiken weergeven.	Subnetlijst
Settings.manage	IP-bereiken weergeven en beheren.	Subnetlijst, maken/bijwerken/verwijderen

Een toegangstoken ophalen

Zie Microsoft Entra zelfstudie voor meer informatie over Microsoft Entra tokens

C gebruiken#

Kopieer/plak de volgende klasse in uw toepassing.
Gebruik de methode AcquireUserTokenAsync met uw toepassings-id, tenant-id en verificatie om een token te verkrijgen.

Opmerking

Hoewel het volgende codevoorbeeld laat zien hoe u een token kunt verkrijgen met behulp van de gebruikersnaam- en wachtwoordstroom, raadt Microsoft u aan veiligere verificatiestromen te gebruiken in een productieomgeving.

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>();
                }
            }
        }
    }
}

Het token valideren

Controleer of u een juist token hebt:

Kopieer/plak in JWT het token dat u in de vorige stap hebt gekregen om het te decoderen.
Controleer of u een 'scp'-claim krijgt met de gewenste app-machtigingen.
In de onderstaande schermopname ziet u een gedecodeerd token dat is verkregen uit de app in de zelfstudie:

Het token gebruiken voor toegang tot de Microsoft Defender for Cloud Apps-API

Kies de API die u wilt gebruiken. Zie Defender for Cloud Apps API voor meer informatie.
Stel de autorisatieheader in de HTTP-aanvraag die u verzendt in op Bearer {token}(Bearer is het autorisatieschema).
De verlooptijd van het token is 1 uur (u kunt meer dan één aanvraag met hetzelfde token verzenden).

Voorbeeld van het verzenden van een aanvraag om een lijst met waarschuwingen op te halen met behulp van 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

Delen via