Komma åt Microsoft Defender for Cloud Apps API med användarkontext

Artikel
11/28/2024

Den här sidan beskriver hur du skapar ett program för att få programmässig åtkomst till Defender for Cloud Apps åt en användare.

Om du behöver programmatisk åtkomst Microsoft Defender for Cloud Apps utan användare kan du läsa Access Microsoft Defender for Cloud Apps med programkontext.

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

Microsoft Defender for Cloud 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å Microsoft Defender for Cloud Apps funktioner. API-åtkomsten kräver OAuth2.0-autentisering. Mer information finns i OAuth 2.0 Authorization Code Flow (OAuth 2.0-auktoriseringskodflöde).

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 Defender for Cloud Apps API

Den här sidan beskriver hur du skapar ett Microsoft Entra program, hämtar en åtkomsttoken för att Microsoft Defender for Cloud Apps och verifiera token.

Obs!

När du använder Microsoft Defender for Cloud 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 på Microsoft Defender for Cloud Apps kan du läsa Hantera administratörsåtkomst.

Tips

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 en app

Registrera ett nytt program i Microsoft Entra administrationscenter. Mer information finns i Snabbstart: Registrera ett program med Microsoft Entra administrationscenter.

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

Namn – Ange ett beskrivande programnamn som 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 ett verksamhetsspecifikt program (LOB). Det här alternativet är inte tillgängligt om du inte registrerar programmet i en katalog. Det här alternativet mappar till Microsoft Entra enda klientorganisation. Det här är standardalternativet om du inte registrerar appen utanför en katalog. I fall där appen är registrerad utanför en katalog är standardvärdet Microsoft Entra flera klientkonton och personliga Microsoft-konton.
Konton i valfri organisationskatalog	Välj det här alternativet om du vill rikta in dig på alla företags- och utbildningskunder. Det här alternativet mappar till en Microsoft Entra enda multitenant. Om du har registrerat appen som Microsoft Entra enda klientorganisation kan du uppdatera den så att den är Microsoft Entra flera klientorganisationer och tillbaka till en enda klientorganisation via fönstret Autentisering.
Konton i valfri organisationskatalog och personliga Microsoft-konton	Välj det här alternativet för att rikta in dig på den bredaste uppsättningen kunder. Det här alternativet mappar till Microsoft Entra flera klientkonton och personliga Microsoft-konton. Om du har registrerat appen som Microsoft Entra flera klientkonton och personliga Microsoft-konton kan du inte ändra detta i användargränssnittet. I stället måste du använda programmanifestredigeraren 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 (mobil & skrivbord) och ange sedan omdirigerings-URI (eller svars-URL) för ditt program.
- För webbprogram anger du bas-URL:en för din app. Kan till exempel http://localhost:31544 vara URL:en för en webbapp som körs på den lokala datorn. Användarna skulle använda den här URL:en för att logga in på 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.
Om du vill se specifika exempel för webbprogram eller interna program kan du läsa våra snabbstarter.

När du är klar väljer du Registrera.

Ge ditt program åtkomst till Microsoft Defender for Cloud Apps och tilldela 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 for Cloud Apps.
- Välj Delegerade behörigheter>Undersökning.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 det API 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 klientorganisations-ID:
- På programsidan går du till Översikt och kopierar följande information:

Behörighetsomfång som stöds

Behörighetsnamn	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 Rapporter för identifieringslista, 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 Rapporter för identifieringslista, listrapportkategorier Uppladdning av identifieringsfil, generera blockskript
Settings.read	Lista IP-intervall.	Undernätslista
Settings.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älvstudien 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 och autentisering för att hämta en token.

Obs!

I följande kodexempel visas hur du hämtar en token med hjälp av användarnamnet och lösenordsflödet, men Microsoft rekommenderar att du använder säkrare autentiseringsflöden i en produktionsmiljö.

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

Verifiera 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
Kontrollera 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 Microsoft Defender for Cloud Apps-API:et

Välj det API som du vill använda. Mer information finns i Defender for Cloud Apps API.
Ange auktoriseringshuvudet i HTTP-begäran som du skickar till "Bearer {token}" (Ägaren ä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 hjälp av 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

Dela via