Åtkomst Microsoft Defender för molnet-appar med programkontext

Artikel
10/20/2023

På den här sidan beskrivs hur du skapar ett program för att få programmatisk åtkomst till Defender för molnet Appar utan användare. Om du behöver programmatisk åtkomst till Defender för molnet-appar för en användares räkning kan du läsa Få å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 för molnet 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å funktionerna i 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änd token för att komma åt API:et Defender för molnet Apps.

Den här artikeln beskriver hur du skapar ett Microsoft Entra-program, hämtar en åtkomsttoken till Microsoft Defender för molnet Appar och validerar token.

Skapa ett program

Logga in på Azure med en användare som har rollen Global administratör .
Gå till Microsoft Entra ID> Appregistreringar> Ny registrering.
I registreringsformuläret väljer du ett namn för ditt program och väljer sedan Registrera.
Om du vill att din app ska få åtkomst till Defender för molnet Appar 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.

Kommentar

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 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 på avsnittet Behörigheter i api:et som du är intresserad av att anropa.
Välj Bevilja administratörsmedgivande.

Kommentar

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 och hemligheter, väljer Ny klienthemlighet, lägger till en beskrivning i hemligheten och väljer sedan Lägg till.

Kommentar

När du har valt Lägg till väljer du kopiera det genererade hemlighetsvärdet. Du kommer inte att kunna hämta det här värdet när du har lämnat.
Skriv ned ditt program-ID och ditt klient-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 för molnet Apps-partner. Ange att appen ska vara flera klientorganisationer (tillgänglig 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 klientorganisationen (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 att din app ska vara 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 klientorganisationer.
Du behöver ditt program som ska godkännas i varje klientorganisation där du tänker använda det. Det beror på att ditt program interagerar Defender för molnet appar för din kunds räkning.

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-0000000000000 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ö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 Microsoft Entra-självstudien.

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 appen (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 = "11111111-1111-1111-1111-111111111111"; // 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

Kommentar

Följande procedur förutsätter att Curl for 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:t för kunden som vill använda din app för att få åtkomst till Defender för molnet 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"}

Validera token

Kontrollera att du har rätt token:

Kopiera och klistra in token som du fick i föregående steg i JWT för att avkoda den.
Verifiera 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 för molnet Apps-roller:

Image of token validation.

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

Välj det API som du vill använda. Mer information finns i API:er för Defender för molnet-appar.
Ange auktoriseringshuvudet i http-begäran som du skickar till "Bearer {token}" (Bearer ä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 få 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

Se även

Hantera API-token

Dela via