Åtkomst Microsoft Defender för molnet Apps API med användarkontext

Artikel
12/11/2023

På den här sidan beskrivs hur du skapar ett program för att få programmatisk åtkomst till Defender för molnet Appar åt en användare.

Om du behöver programmatisk åtkomst Microsoft Defender för molnet Appar utan användare kan du läsa Access Microsoft Defender för molnet Apps med programkontext.

Om du inte är säker på vilken åtkomst du behöver kan du läsa sidan Introduktion.

Microsoft Defender för molnet Apps exponerar mycket av sina data och åtgärder via en uppsättning programmatiska API:er. Med dessa API:er kan du automatisera arbetsflöden och innovationer baserat på funktionerna i Microsoft Defender för molnet Apps. API-åtkomsten kräver OAuth2.0-autentisering. Mer information finns i OAuth 2.0 Authorization Code Flow.

I allmänhet måste du vidta följande steg för att använda API:erna:

Skapa ett Microsoft Entra-program
Hämta en åtkomsttoken med det här programmet
Använda token för att komma åt API:et för Defender för molnet-appar

På den här sidan beskrivs hur du skapar ett Microsoft Entra-program, hämtar en åtkomsttoken för att Microsoft Defender för molnet Appar och validera token.

Kommentar

När du kommer åt Microsoft Defender för molnet Apps API för en användares räkning behöver du rätt programbehörighet och användarbehörighet. Om du inte är bekant med användarbehörigheter för Microsoft Defender för molnet-appar kan du läsa Hantera administratörsåtkomst.

Dricks

Om du har behörighet att utföra en åtgärd i portalen har du behörighet att utföra åtgärden i API:et.

Skapa ett program

Logga in på Azure med ett användarkonto som har rollen Global administratör .
Gå till Microsoft Entra ID> Appregistreringar> Ny registrering.

När sidan registrera ett program visas anger du programmets registreringsinformation:

Namn – ange ett beskrivande programnamn som ska visas för appens användare.

Kontotyper som stöds – välj vilka konton som du vill att programmet ska stödja.

Kontotyper som stöds	Beskrivning
Endast konton i den här organisationskatalogen	Välj det här alternativet om du skapar en verksamhetsspecifik app. Det här alternativet är inte tillgängligt om du inte registrerar programmet i en katalog. Det här alternativet mappar till endast Microsoft Entra-klientorganisation. Det här är standardalternativet såvida du inte registrerar appen utanför en katalog. I fall där appen är registrerad utanför en katalog är standardvärdet Microsoft Entra-konton för flera innehavare och personliga Microsoft-konton.
Konton i valfri organisationskatalog	Välj det här alternativet om du vill rikta dig till mot alla företags- och utbildningskunder. Det här alternativet mappar till en Microsoft Entra-klientorganisation med endast Microsoft. Om du har registrerat appen som endast Microsoft Entra-klientorganisation kan du uppdatera den till Microsoft Entra multi-tenant och tillbaka till en enda klient via fönstret Autentisering .
Konton i en valfri organisationskatalog och personliga Microsoft-konton	Välj det här alternativet om du vill rikta de bredaste kunduppsättningarna. Det här alternativet mappar till Microsoft Entra-konton för flera innehavare och personliga Microsoft-konton. Om du har registrerat appen som Microsoft Entra-konton för flera innehavare och personliga Microsoft-konton kan du inte ändra detta i användargränssnittet. I stället måste du använda programmets manifestredigeraren för att ändra de kontotyper som stöds.

Omdirigerings-URI (valfritt) – välj den typ av app som du skapar, Webb eller Offentlig klient (mobila och skrivbord), och sedan ange omdirigerings-URI (eller svars-URL) för programmet.
- För webbappar anger du grundläggande URL för appen. Till exempel kan http://localhost:31544 vara URL för en webbapp som körs på din lokala dator. Användare skulle då använda den här URL:en för att logga in till ett webbklientprogram.
- För offentliga klientprogram anger du den URI som används av Microsoft Entra-ID för att returnera tokensvar. Ange ett värde som är specifikt för ditt program, till exempel myapp://auth.
Specifika exempel på webbappar och interna program finns i snabbstarterna.

När det är klart väljer du Registrera.

Tillåt att ditt program får åtkomst till Microsoft Defender för molnet-appar och tilldela det behörigheten Läs aviseringar:
- På programsidan väljer du API-behörigheter>Lägg till behörighets-API>:er som min organisation använder> skriver Microsoft Cloud App Security och väljer sedan Microsoft Cloud App Security.
- Obs! Microsoft Cloud App Security visas inte i den ursprungliga listan. Börja skriva dess namn i textrutan för att se det visas. Se till att skriva det här namnet, även om produkten nu kallas Defender för molnet Apps.
- Välj Undersökning av delegerade behörigheter.Läs>> välj Lägg till behörigheter
- Viktigt: Välj relevanta behörigheter. Investigation.Read är bara ett exempel. Andra behörighetsomfång finns i Behörighetsomfång som stöds
  - Om du vill ta reda på vilken behörighet du behöver kan du läsa avsnittet Behörigheter i api:et som du är intresserad av att anropa.
- Välj Bevilja administratörsmedgivande
  
  Obs! Varje gång du lägger till behörighet måste du välja Bevilja administratörsmedgivande för att den nya behörigheten ska börja gälla.
Skriv ned ditt program-ID och ditt klient-ID:
- På programsidan går du till Översikt och kopierar följande information:

Behörighetsomfång som stöds

Behörighetens namn	beskrivning	Åtgärder som stöds
Investigation.read	Utför alla åtgärder som stöds för aktiviteter och aviseringar förutom att stänga aviseringar. Visa IP-intervall men inte lägga till, uppdatera eller ta bort. Utför alla entitetsåtgärder.	Aktivitetslista, hämtning, feedback Aviseringslista, hämta, markera som läst/oläst Entitetslista, hämta, hämta träd Undernätslista
Investigation.manage	Utför alla investigation.read-åtgärder utöver att hantera aviseringar och IP-intervall.	Aktivitetslista, hämtning, feedback Aviseringslista, hämta, markera som läst/oläst, stäng Entitetslista, hämta, hämta träd Undernätslista, skapa/uppdatera/ta bort
Discovery.read	Utför alla åtgärder som stöds för aktiviteter och aviseringar förutom att stänga aviseringar. Lista identifieringsrapporter och kategorier.	Aviseringslista, hämta, markera som läst/oläst Identifieringslistarapporter, listrapportkategorier
Discovery.manage	Behörigheter för Discovery.read Stäng aviseringar, ladda upp identifieringsfiler och generera blockskript	Aviseringslista, hämta, markera som läst/oläst, stäng Identifieringslistarapporter, listrapportkategorier Uppladdning av identifieringsfil, generera blockskript
Inställningar.read	Lista IP-intervall.	Undernätslista
Inställningar.manage	Lista och hantera IP-intervall.	Undernätslista, skapa/uppdatera/ta bort

Hämta en åtkomsttoken

Mer information om Microsoft Entra-token finns i Självstudie om Microsoft Entra

Använda C#

Kopiera/klistra in följande klass i ditt program.

Använd metoden AcquireUserTokenAsync med ditt program-ID, klientorganisations-ID, användarnamn och lösenord för att hämta en token.

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

Validera token

Kontrollera att du har rätt token:

Kopiera/klistra in den token som du fick i föregående steg i JWT för att avkoda den
Verifiera att du får ett scp-anspråk med önskade appbehörigheter
I skärmbilden nedan kan du se en avkodad token som hämtats från appen i självstudien:

Använda token för att komma åt API:et Microsoft Defender för molnet Apps

Välj det API som du vill använda. Mer information finns i Defender för molnet Apps API.
Ange auktoriseringshuvudet i HTTP-begäran som du skickar till "Bearer {token}" (Bearer är auktoriseringsschemat)
Förfallotiden för token är 1 timme (du kan skicka fler än en begäran med samma token)

Exempel på hur du skickar en begäran om att hämta en lista över aviseringar med 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