Del via

Adgang Microsoft Defender for Cloud Apps API med brugerkontekst

  • Artikel

På denne side beskrives det, hvordan du opretter et program for at få programmatisk adgang til Defender for Cloud Apps på vegne af en bruger.

Hvis du har brug for programadgang Microsoft Defender for Cloud Apps uden en bruger, skal du se Access Microsoft Defender for Cloud Apps med programkontekst.

Hvis du ikke er sikker på, hvilken adgang du har brug for, kan du læse siden Introduktion.

Microsoft Defender for Cloud Apps fremviser mange af sine data og handlinger via et sæt programmatiske API'er. Disse API'er gør det muligt for dig at automatisere arbejdsflows og skabe innovation baseret på Microsoft Defender for Cloud Apps funktioner. API-adgangen kræver OAuth2.0-godkendelse. Du kan få flere oplysninger under OAuth 2.0 Authorization Code Flow.

Generelt skal du gøre følgende for at bruge API'erne:

  • Opret et Microsoft Entra program
  • Hent et adgangstoken ved hjælp af dette program
  • Brug tokenet til at få adgang til Defender for Cloud Apps API

På denne side forklares det, hvordan du opretter et Microsoft Entra program, får et adgangstoken til Microsoft Defender for Cloud Apps og validerer tokenet.

Bemærk!

Når du får adgang til Microsoft Defender for Cloud Apps API på vegne af en bruger, skal du have den korrekte programtilladelse og brugertilladelse. Hvis du ikke kender brugertilladelser til Microsoft Defender for Cloud Apps, skal du se Administrer administratoradgang.

Tip

Hvis du har tilladelse til at udføre en handling på portalen, har du tilladelse til at udføre handlingen i API'en.

Opret en app

  1. Registrer et nyt program i Microsoft Entra-administrationscenter. Du kan få flere oplysninger under Hurtig start: Registrer et program med Microsoft Entra-administrationscenter.

  2. Når siden Registrer et program vises, skal du angive registreringsoplysningerne for dit program:

    • Navn – Angiv et sigende programnavn, der vises for brugerne af appen.

    • Understøttede kontotyper – Vælg, hvilke konti dit program skal understøtte.

      Understøttede kontotyper Beskrivelse
      Kun konti i denne organisationsmappe Vælg denne indstilling, hvis du opretter et line of business-program (LOB). Denne indstilling er ikke tilgængelig, hvis du ikke registrerer programmet i en mappe.

      Denne indstilling knyttes til kun Microsoft Entra enkeltlejer.

      Dette er standardindstillingen, medmindre du registrerer appen uden for en mappe. I de tilfælde, hvor appen er registreret uden for en mappe, er standarden Microsoft Entra multitenant- og personlige Microsoft-konti.
      Konti i en hvilken som helst organisationsmappe Vælg denne indstilling, hvis du vil målrette mod alle forretnings- og uddannelseskunder.

      Denne indstilling knyttes til et multitenant, der kun Microsoft Entra.

      Hvis du har registreret appen som Microsoft Entra enkeltlejer, kan du opdatere den til at være Microsoft Entra multitenant og tilbage til enkeltlejer via ruden Godkendelse.
      Konti i en hvilken som helst organisationsmappe og personlige Microsoft-konti Vælg denne indstilling for at målrette det bredeste sæt kunder.

      Denne indstilling knyttes til Microsoft Entra multitenant- og personlige Microsoft-konti.

      Hvis du har registreret appen som Microsoft Entra multitenant- og personlige Microsoft-konti, kan du ikke ændre dette i brugergrænsefladen. Du skal i stedet bruge programmanifesteditoren til at ændre de understøttede kontotyper.

    • Omdiriger URI (valgfrit) – Vælg den apptype, du bygger, **Web eller Offentlig klient (mobil & desktop), og angiv derefter omdirigerings-URI'en (eller svar-URL-adressen) for dit program.

      • I forbindelse med webprogrammer skal du angive den grundlæggende URL-adresse til din app. Det kan f.eks. være URL-adressen til en webapp, http://localhost:31544 der kører på din lokale computer. Brugerne skal bruge denne URL-adresse til at logge på et webklientprogram.
      • I forbindelse med offentlige klientprogrammer skal du angive den URI, der bruges af Microsoft Entra ID til at returnere tokensvar. Angiv en værdi, der er specifik for dit program, f.eks myapp://auth. .

      Hvis du vil se specifikke eksempler på webprogrammer eller oprindelige programmer, kan du se vores hurtige introduktioner.

      Når du er færdig, skal du vælge Registrer.

  3. Giv dit program adgang til Microsoft Defender for Cloud Apps og tildele det tilladelsen "Læs beskeder":

    • Vælg API-tilladelser>TilføjtilladelseS-API'er>, som min organisation bruger>, på din programside, skriv Microsoft Cloud App Security, og vælg derefter Microsoft Cloud App Security.

    • Bemærk! Microsoft Cloud App Security vises ikke på den oprindelige liste. Begynd at skrive navnet i tekstfeltet for at se det blive vist. Sørg for at skrive dette navn, selvom produktet nu kaldes Defender for Cloud Apps.

      Skærmbillede af tilføjelse af tilladelser.

    • Vælg Delegerede tilladelser>Undersøgelse.Læs> vælg Tilføj tilladelser

      Skærmbillede af tilføjelse af programtilladelser.

    • Vigtig bemærkning: Vælg de relevante tilladelser. Investigation.Read er kun et eksempel. Du kan få mere at vide om andre tilladelsesområder under Understøttede tilladelsesområder

      • Hvis du vil finde ud af, hvilken tilladelse du har brug for, skal du se afsnittet Tilladelser i den API, du er interesseret i at ringe til.

    • Vælg Tildel administratorsamtykke

      Bemærk! Hver gang du tilføjer tilladelse, skal du vælge Giv administratorsamtykke , for at den nye tilladelse kan træde i kraft.

      Skærmbillede af tildeling af administratortilladelser.

  4. Skriv dit program-id og dit lejer-id ned:

    • Gå til Oversigt på din programside, og kopiér følgende oplysninger:

      Skærmbillede af det oprettede app-id.

Understøttede tilladelsesområder

Tilladelsesnavn Beskrivelse Understøttede handlinger
Investigation.read Udfør alle understøttede handlinger på aktiviteter og beskeder undtagen lukning af beskeder.
Få vist IP-intervaller, men tilføj, opdater eller slet ikke.

Udfør alle objekters handlinger.		 Aktivitetsliste, hentning, feedback
Beskedliste, hent, markér som læst/ulæst
Liste over enheder, hentning, hentningstræ
Undernetliste
Investigation.manage Udfør alle investigation.read-handlinger ud over administration af beskeder og IP-intervaller. Aktivitetsliste, hentning, feedback
Beskedliste, hent, markér som læst/ulæst, luk
Liste over enheder, hentning, hentningstræ
Undernetliste, opret/opdater/slet
Discovery.read Udfør alle understøttede handlinger på aktiviteter og beskeder undtagen lukning af beskeder.
Vis registreringsrapporter og -kategorier.		 Beskedliste, hent, markér som læst/ulæst
Registreringslisterapporter, listerapportkategorier
Discovery.manage Discovery.read-tilladelser
Luk beskeder, upload registreringsfiler, og generér blokscripts		 Beskedliste, hent, markér som læst/ulæst, luk
Registreringslisterapporter, listerapportkategorier
Overførsel af registreringsfil, generer blokscript
Settings.read Vis IP-områder. Undernetliste
Settings.manage Vis og administrer IP-områder. Undernetliste, opret/opdater/slet

Hent et adgangstoken

Du kan få flere oplysninger om Microsoft Entra tokens i Microsoft Entra selvstudium

Brug af C#

  • Kopiér/indsæt følgende klasse i programmet.
  • Brug metoden AcquireUserTokenAsync med dit program-id, lejer-id og godkendelse til at hente et token.

Bemærk!

Selvom følgende kodeeksempel viser, hvordan du henter et token ved hjælp af flowet for brugernavn og adgangskode, anbefaler Microsoft, at du bruger mere sikre godkendelsesflows i et 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>();
                }
            }
        }
    }
}

Valider tokenet

Kontrollér, at du har fået et korrekt token:

  • Kopiér/indsæt i JWT det token, du fik i det forrige trin, for at afkode det

  • Valider, at du får et 'scp'-krav med de ønskede apptilladelser

  • På skærmbilledet nedenfor kan du se et afkodet token, der er hentet fra appen, i selvstudiet:

    Skærmbillede af tokenvalidering.

Brug tokenet til at få adgang til api'en til Microsoft Defender for Cloud Apps

  • Vælg den API, du vil bruge. Du kan få flere oplysninger under Defender for Cloud Apps API.

  • Angiv godkendelsesheaderen i den HTTP-anmodning, du sender til "Ihændehaver {token}" (ihændehaver er autorisationsskemaet)

  • Tokenets udløbstid er 1 time (du kan sende mere end én anmodning med det samme token)

  • Eksempel på afsendelse af en anmodning om at få vist en liste over beskeder ved hjælp af 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

Se også