Åtkomst Microsoft Defender for Cloud Apps med programkontext

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 utan en användare. Om du behöver programmatisk åtkomst till Defender for Cloud Apps för en användares räkning kan du läsa Hämta åtkomst med användarkontext. Om du inte är säker på vilken åtkomst du behöver kan du läsa sidan Hantera API-token .

Microsoft Defender for Cloud Apps exponerar mycket av sina data och åtgärder via en uppsättning programmatiska API:er. Dessa API:er hjälper dig att automatisera arbetsflöden och innovationer baserat på 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änd token för att komma åt Defender for Cloud Apps API.

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

Skapa en app för Defender for Cloud Apps

Registrera ett nytt program i Microsoft Entra administrationscenter. Mer information finns i Snabbstart: Registrera ett program med Microsoft Entra administrationscenter.
Om du vill att din app ska få åtkomst till Defender for Cloud Apps och tilldela den behörigheten Läs alla aviseringar 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 Programbehörigheter>Investigation.Read och välj sedan Lägg till behörigheter.
  
  Du måste välja 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 titta i 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 en behörighet måste du välja Bevilja administratörsmedgivande för att den nya behörigheten ska börja gälla.
Om du vill lägga till en hemlighet i programmet väljer du Certifikat & hemligheter, väljer Ny klienthemlighet, lägger till en beskrivning i hemligheten och väljer sedan Lägg till.

Obs!

När du har valt Lägg till väljer du kopiera det genererade hemlighetsvärdet. Du kan inte hämta det här värdet när du har lämnat.
Skriv ned ditt program-ID och ditt klientorganisations-ID. På programsidan går du till Översikt och kopierar program-ID:t (klient)-ID:t och katalog-ID:t (klientorganisation).
Endast för Microsoft Defender for Cloud Apps partner. Ange att din app ska ha flera klientorganisationer (tillgängligt i alla klienter efter medgivande). Detta krävs för appar från tredje part (till exempel om du skapar en app som är avsedd att köras i flera kunders klientorganisation). Detta krävs inte om du skapar en tjänst som du bara vill köra i din klientorganisation (till exempel om du skapar ett program för din egen användning som bara interagerar med dina egna data). Så här ställer du in appen på flera klientorganisationer:
- Gå till Autentisering och lägg till https://portal.azure.com som omdirigerings-URI.
- Längst ned på sidan, under Kontotyper som stöds, väljer du Konton i alla organisationskatalogprogramsmedgivande för din app för flera klienter.
Du behöver ditt program för att godkännas i varje klientorganisation där du tänker använda det. Det beror på att ditt program interagerar Defender for Cloud Apps åt kunden.

Du (eller din kund om du skriver en app från tredje part) måste välja medgivandelänken och godkänna din app. Medgivandet ska göras med en användare som har administratörsbehörighet i Active Directory.

Medgivandelänken skapas på följande sätt:
```
https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true
```
Där 000000000-0000-0000-0000-00000000000 ersätts med ditt program-ID.

Klart! Du har registrerat ett program! Se exempel nedan för tokenförvärv och validering.

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

Använda C#

Följande kod testades med NuGet Microsoft.Identity.Client 4.47.2.

Skapa ett nytt konsolprogram.
Installera NuGet Microsoft.Identity.Client.
Lägg till följande:
```
using Microsoft.Identity.Client;
```

Kopiera och klistra in följande kod i din app (glöm inte att uppdatera de tre variablerna: 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;

Använda Python

Se Microsoft Authentication Library (MSAL) för Python.

Använda Curl

Obs!

Följande procedur förutsätter att Curl för Windows redan är installerat på datorn.

Öppna en kommandotolk och ange CLIENT_ID till ditt Azure-program-ID.
Ange CLIENT_SECRET till din Azure-programhemlighet.
Ange TENANT_ID till Azure-klientorganisations-ID för kunden som vill använda din app för att få åtkomst till Defender for Cloud Apps.
Kör följande 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 ett svar i följande formulär:

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

Verifiera token

Kontrollera att du har rätt token:

Kopiera och 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 rollanspråk med önskade behörigheter
I följande bild kan du se en avkodad token som hämtats från en app med behörighet till alla Microsoft Defender for Cloud Apps roller:

Skärmbild av tokenverifiering.

Använda token för att komma åt Microsoft Defender for Cloud Apps API

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

Följande är ett 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

Se även

Hantera API-token

Dela via