Toegang tot Microsoft Defender voor Cloud Apps-API met gebruikerscontext

Artikel
08/12/2024

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

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

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

Microsoft Defender voor 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 voor Cloud Apps-mogelijkheden. Voor de API-toegang is OAuth2.0-verificatie vereist. Zie OAuth 2.0 Authorization Code Flow 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 deze toepassing
Het token gebruiken om toegang te krijgen tot Defender voor Cloud Apps-API

Op deze pagina wordt uitgelegd hoe u een Microsoft Entra-toepassing maakt, een toegangstoken opvragen Microsoft Defender voor Cloud Apps en het token valideert.

Notitie

Wanneer u namens een gebruiker toegang krijgt tot Microsoft Defender voor Cloud Apps-API, hebt u de juiste toepassingsmachtiging en gebruikersmachtiging nodig. Zie Beheerderstoegang beheren als u niet bekend bent met gebruikersmachtigingen voor Microsoft Defender voor 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 een nieuwe toepassing in het Microsoft Entra-beheercentrum. Zie Quickstart: Een toepassing registreren bij het 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 aan gebruikers van de app.

Ondersteunde accounttypen: selecteer voor welke accounts de toepassing ondersteuning moet bieden.

Ondersteunde rekeningtypen	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 in een map registreert. Deze optie wordt toegewezen aan Microsoft Entra-only single-tenant. Dit is de standaardoptie tenzij u de app registreert buiten een map. 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 alle zakelijke klanten en onderwijsinstellingen wilt bereiken. Deze optie wordt toegewezen aan een multitenant van Microsoft Entra. Als u de app hebt geregistreerd als één tenant van Microsoft Entra, kunt u deze bijwerken naar Microsoft Entra multitenant en terug naar één tenant via het deelvenster Verificatie .
Accounts in elke organisatiemap en persoonlijke Microsoft-accounts	Selecteer deze optie als u de breedste groep klanten wilt bereiken. Deze optie wordt toegewezen aan Microsoft Entra-accounts met meerdere tenants en persoonlijke Microsoft-accounts. Als u de app hebt geregistreerd als Microsoft Entra-accounts voor meerdere tenants en persoonlijke Microsoft-accounts, kunt u deze niet wijzigen in de gebruikersinterface. In plaats daarvan moet u de Application Manifest Editor gebruiken om de ondersteunde rekeningtypen te wijzigen.

Omleidings-URI (optioneel): selecteer het type app dat u bouwt, **Web of Openbare client (mobiel en desktop) en voer vervolgens de omleidings-URI (of antwoord-URL) voor uw toepassing in.
- Geef voor webtoepassingen de basis-URL van de app op. http://localhost:31544 kan bijvoorbeeld de URL zijn van een web-app die op uw lokale machine wordt uitgevoerd. Gebruikers moeten deze URL gebruiken om zich bij een webclienttoepassing aan te melden.
- 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 de toepassing, zoals myapp://auth.
Raadpleeg onze snelstarts om specifieke voorbeelden te zien van webtoepassingen of systeemeigen toepassingen.

Selecteer Registreren wanneer u klaar bent.

Sta toe dat uw toepassing toegang heeft tot Microsoft Defender voor Cloud Apps en wijs deze machtiging Leeswaarschuwingen toe:
- Selecteer op uw toepassingspagina API-machtigingen>toevoegen machtigings-API's>die mijn organisatie gebruikt> het type 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 wordt het product nu Defender voor Cloud Apps genoemd.
- Kies Gedelegeerde machtigingen>Investigation.Read> 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

Machtigingnaam	Beschrijving	Ondersteunde acties
Investigation.read	Alle ondersteunde acties uitvoeren voor activiteiten en waarschuwingen, behalve waarschuwingen sluiten. IP-bereiken weergeven, maar niet toevoegen, bijwerken of verwijderen. Voer alle acties voor entiteiten uit.	Lijst met activiteiten, ophalen, feedback Lijst met waarschuwingen, ophalen, markeren als gelezen/ongelezen Lijst met entiteiten, ophalen, ophalen, ophalen van structuur Subnetlijst
Investigation.manage	Voer alle investigation.read-acties uit naast het beheren van waarschuwingen en IP-bereiken.	Lijst met activiteiten, ophalen, feedback Lijst met waarschuwingen, ophalen, markeren als gelezen/ongelezen, sluiten Lijst met entiteiten, ophalen, ophalen, ophalen van structuur Subnetlijst, maken/bijwerken/verwijderen
Discovery.read	Alle ondersteunde acties uitvoeren voor activiteiten en waarschuwingen, behalve waarschuwingen 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
Settings.read	IP-bereiken weergeven.	Subnetlijst
Settings.manage	IP-bereiken weergeven en beheren.	Subnetlijst, maken/bijwerken/verwijderen

Een toegangstoken opvragen

Zie de zelfstudie Microsoft Entra 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.

Notitie

Hoewel het volgende codevoorbeeld laat zien hoe u een token verkrijgt met behulp van de gebruikersnaam- en wachtwoordstroom, raadt Microsoft u aan om 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 correct token hebt:

Kopiëren/plakken 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 om toegang te krijgen tot de MICROSOFT DEFENDER VOOR CLOUD Apps-API

Kies de API die u wilt gebruiken. Zie Defender voor Cloud Apps-API voor meer informatie.
Stel de autorisatieheader in de HTTP-aanvraag in die u verzendt naar 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 voor het ophalen van een lijst met waarschuwingen 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

Share via