Del via

Adgang Microsoft Defender for Cloud Apps med programkontekst

  • Artikel

På denne side beskrives det, hvordan du opretter et program for at få programmatisk adgang til Defender for Cloud Apps uden en bruger. Hvis du har brug for programmatisk adgang til Defender for Cloud Apps på vegne af en bruger, skal du se Få adgang med brugerkontekst. Hvis du ikke er sikker på, hvilken adgang du har brug for, kan du se siden Administration af API-tokens .

Microsoft Defender for Cloud Apps fremviser mange af sine data og handlinger via et sæt programmatiske API'er. Disse API'er hjælper dig med at automatisere arbejdsflows og skabe innovation baseret på 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.

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

Opret en app til Defender for Cloud Apps

  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. Hvis du vil give din app adgang til Defender for Cloud Apps og tildele den tilladelsen "Læs alle beskeder", skal du vælge API-tilladelser>TilføjtilladelseS-API'er>, som min organisation bruger>, skrive Microsoft Cloud App Security og derefter vælge 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 tilladelse.

    • Vælg Programtilladelser>Investigation.Read, og vælg derefter Tilføj tilladelser.

      Skærmbillede af tilføjelse af app-tilladelse.

      Du skal vælge 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.

  3. Vælg Giv administratorsamtykke.

    Bemærk!

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

    Skærmbillede af tildeling af administratortilladelser.

  4. Hvis du vil føje en hemmelighed til programmet, skal du vælge Certifikater & hemmeligheder, vælge Ny klienthemmelighed, føje en beskrivelse til hemmeligheden og derefter vælge Tilføj.

    Bemærk!

    Når du har valgt Tilføj, skal du vælge kopiér den genererede værdi for hemmelighed. Du kan ikke hente denne værdi, når du er gået.

    Skærmbillede af oprettelse af en appnøgle.

  5. Skriv dit program-id og dit lejer-id ned. På din programside skal du gå til Oversigt og kopiere program-id'et (klient)-id'et og mappe-id'et (lejeren).

    Skærmbillede af det oprettede app-id.

  6. Kun for Microsoft Defender for Cloud Apps partnere. Indstil din app til at være multitenanted (tilgængelig i alle lejere efter samtykke). Dette er påkrævet for tredjepartsapps (hvis du f.eks. opretter en app, der er beregnet til at køre i flere kunders lejer). Dette er ikke påkrævet , hvis du opretter en tjeneste, som du kun vil køre i din lejer (hvis du f.eks. opretter et program til dit eget forbrug, der kun interagerer med dine egne data). Sådan angiver du, at din app skal multitenanted:

    • Gå til Godkendelse, og tilføj https://portal.azure.com som omdirigerings-URI'en.

    • Nederst på siden under Understøttede kontotyper skal du vælge Konti i alle organisationsmappeprogrammers samtykke til din multitenantapp.

    Du skal have dit program godkendt i hver lejer, hvor du vil bruge det. Det skyldes, at dit program interagerer Defender for Cloud Apps på vegne af din kunde.

    Du (eller din kunde, hvis du skriver en tredjepartsapp), skal vælge samtykkelinket og godkende din app. Samtykket skal udføres med en bruger, der har administrative rettigheder i Active Directory.

    Samtykkelinket er udformet på følgende måde:

    https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true

    Hvor 00000000-0000-0000-0000-00000000000 erstattes med dit program-id.

Gjort! Du har registreret et program! Se eksempler nedenfor for at få oplysninger om tokenerhvervelse og -validering.

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 selvstudiet om Microsoft Entra.

Brug PowerShell

# This script acquires the App Context Token and stores it in the variable $token for later use in the script.
# Paste your Tenant ID, App ID, and App Secret (App key) into the indicated quotes below.

$tenantId = '' ### Paste your tenant ID here
$appId = '' ### Paste your Application ID here
$appSecret = '' ### Paste your Application key here

$resourceAppIdUri = '05a65629-4c1b-48c1-a78b-804c4abdd4af'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
$authBody = [Ordered] @{
    resource = "$resourceAppIdUri"
    client_id = "$appId"
    client_secret = "$appSecret"
    grant_type = 'client_credentials'
}
$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token

Brug C#

Følgende kode blev testet med NuGet Microsoft.Identity.Client 4.47.2.

  1. Opret et nyt konsolprogram.

  2. Installér NuGet Microsoft.Identity.Client.

  3. Tilføj følgende:

    using Microsoft.Identity.Client;

  4. Kopiér og indsæt følgende kode i din app (glem ikke at opdatere de tre variabler: tenantId, appId, appSecret):

    string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here
string appId = "00001111-aaaa-2222-bbbb-3333cccc4444"; // Paste your own app ID here
string appSecret = "22222222-2222-2222-2222-222222222222"; // Paste your own app secret here for a test, and then store it in a safe place!
const string authority = "https://login.microsoftonline.com";
const string audience = "05a65629-4c1b-48c1-a78b-804c4abdd4af";

IConfidentialClientApplication myApp = ConfidentialClientApplicationBuilder.Create(appId).WithClientSecret(appSecret).WithAuthority($"{authority}/{tenantId}").Build();

List scopes = new List() { $"{audience}/.default" };

AuthenticationResult authResult = myApp.AcquireTokenForClient(scopes).ExecuteAsync().GetAwaiter().GetResult();

string token = authResult.AccessToken;

Brug Python

Se Microsoft Authentication Library (MSAL) for Python.

Brug krøllede

Bemærk!

I følgende procedure antages det, at Curl til Windows allerede er installeret på computeren.

  1. Åbn en kommandoprompt, og angiv CLIENT_ID til dit Azure-program-id.
  2. Angiv CLIENT_SECRET til din Azure-programhemmelighed.
  3. Angiv TENANT_ID til azure-lejer-id'et for den kunde, der vil bruge din app til at få adgang til Defender for Cloud Apps.
  4. Kør følgende kommando:
curl -i -X POST -H "Content-Type:application/x-www-form-urlencoded" -d "grant_type=client_credentials" -d "client_id=%CLIENT_ID%" -d "scope=05a65629-4c1b-48c1-a78b-804c4abdd4af/.default" -d "client_secret=%CLIENT_SECRET%" "https://login.microsoftonline.com/%TENANT_ID%/oauth2/v2.0/token" -k

Du får et svar i følgende form:

{"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn <truncated> aWReH7P0s0tjTBX8wGWqJUdDA"}

Valider tokenet

Sørg for, at du har det korrekte token:

  1. Kopiér og indsæt det token, du fik i det forrige trin, i JWT for at afkode det.
  2. Valider, at du får et krav om "roller" med de ønskede tilladelser
  3. På følgende billede kan du se et afkodet token, der er hentet fra en app med tilladelser til alle Microsoft Defender for Cloud Apps roller:

Skærmbillede af tokenvalidering.

Brug tokenet til at få adgang til Microsoft Defender for Cloud Apps API

  1. Vælg den API, du vil bruge. Du kan få flere oplysninger under Defender for Cloud Apps API'er.
  2. Angiv godkendelsesheaderen i den http-anmodning, du sender til "Ihændehaver {token}" (Ihændehaver er godkendelsesskemaet).
  3. Tokenets udløbstid er én time. Du kan sende mere end én anmodning med det samme token.

Følgende er et eksempel på afsendelse af en anmodning om at få 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å