Toegang tot Microsoft Defender for Cloud Apps API met gebruikerscontext

Artikel
11/28/2024

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

Wanneer u Microsoft Defender for Cloud Apps API namens een gebruiker opent, hebt u de juiste toepassingsmachtiging en gebruikersmachtiging nodig. Zie Beheerderstoegang beheren als u niet bekend bent met gebruikersmachtigingen op 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
- Belangrijke 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