Toegang tot Microsoft Defender voor Cloud Apps met toepassingscontext

Artikel
12/11/2023

Op deze pagina wordt beschreven hoe u een toepassing maakt om programmatische toegang te krijgen tot Defender voor Cloud Apps zonder gebruiker. Als u programmatische toegang nodig hebt tot Defender voor Cloud Apps namens een gebruiker, raadpleegt u Toegang krijgen met gebruikerscontext. Als u niet zeker weet welke toegang u nodig hebt, raadpleegt u de pagina API-tokens beheren.

Microsoft Defender voor Cloud Apps maakt veel van de gegevens en acties beschikbaar via een set programmatische API's. Deze API's helpen u bij het automatiseren van werkstromen en innoveren op basis van Defender voor Cloud Apps-mogelijkheden. Voor de API-toegang is OAuth2.0-verificatie vereist. Zie OAuth 2.0 Authorization Code Flow voor meer informatie.

Over het algemeen moet u de volgende stappen uitvoeren om de API's te gebruiken:

Maak een Microsoft Entra-toepassing.
Haal een toegangstoken op met behulp van deze toepassing.
Gebruik het token om toegang te krijgen tot Defender voor Cloud Apps-API.

In dit artikel wordt uitgelegd hoe u een Microsoft Entra-toepassing maakt, een toegangstoken opvragen Microsoft Defender voor Cloud Apps en het token valideert.

Een app maken

Meld u aan bij Azure met een gebruiker met de rol Global Beheer istrator.
Navigeer naar Microsoft Entra-id> App-registraties> Nieuwe registratie.
Kies in het registratieformulier een naam voor uw toepassing en selecteer Vervolgens Registreren.
Als u wilt dat uw app toegang krijgt tot Defender voor Cloud Apps en deze machtiging Alle waarschuwingen lezen toewijst, selecteert u API-machtigingen>toevoegen api's die>door mijn organisatie worden gebruikt>, typt u Microsoft Cloud App Security en selecteert u Vervolgens Microsoft Cloud App Security.

Notitie

Microsoft Cloud App Security wordt niet weergegeven in de oorspronkelijke lijst. Begin met het schrijven van de naam in het tekstvak om deze weer te geven. Zorg ervoor dat u deze naam typt, ook al wordt het product nu Defender voor Cloud Apps genoemd.
- Selecteer Toepassingsmachtigingen>Investigation.Read en selecteer vervolgens Machtigingen toevoegen.
  
  U moet de relevante machtigingen selecteren. Investigation.Read is slechts een voorbeeld. Zie Ondersteunde machtigingsbereiken voor andere machtigingsbereiken
  - Als u wilt bepalen welke machtiging u nodig hebt, bekijkt u de sectie Machtigingen in de API die u wilt aanroepen.
Selecteer Beheerderstoestemming verlenen.

Notitie

Telkens wanneer u een machtiging toevoegt, moet u Beheerderstoestemming verlenen selecteren om de nieuwe machtiging van kracht te laten worden.
Als u een geheim aan de toepassing wilt toevoegen, selecteert u Certificaten en geheimen, selecteert u Nieuw clientgeheim, voegt u een beschrijving toe aan het geheim en selecteert u Vervolgens Toevoegen.

Notitie

Nadat u Toevoegen hebt geselecteerd, selecteert u de gegenereerde geheime waarde kopiëren. U kunt deze waarde niet ophalen nadat u vertrekt.
Noteer uw toepassings-id en uw tenant-id. Ga op de toepassingspagina naar Overzicht en kopieer de toepassings-id (client) en de map-id (tenant).
Alleen voor Microsoft Defender voor Cloud Apps-partners. Stel uw app in op meerdere tenants (beschikbaar in alle tenants na toestemming). Dit is vereist voor apps van derden (bijvoorbeeld als u een app maakt die is bedoeld voor uitvoering in de tenant van meerdere klanten). Dit is niet vereist als u een service maakt die u alleen in uw tenant wilt uitvoeren (bijvoorbeeld als u een toepassing voor uw eigen gebruik maakt die alleen met uw eigen gegevens werkt). Uw app instellen op meerdere tenants:
- Ga naar Verificatie en voeg deze toe https://portal.azure.com als omleidings-URI.
- Selecteer onder aan de pagina onder Ondersteunde accounttypen de accounts in elke organisatiemaptoepassingstoestemming voor uw app met meerdere tenants.
U moet uw toepassing goedkeuren in elke tenant waar u deze wilt gebruiken. Dit komt doordat uw toepassing namens uw klant Defender voor Cloud Apps communiceert.

U (of uw klant als u een app van derden schrijft) moet de toestemmingskoppeling selecteren en uw app goedkeuren. De toestemming moet worden uitgevoerd met een gebruiker met beheerdersbevoegdheden in Active Directory.

De toestemmingskoppeling wordt als volgt gevormd:
```
https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true
```
Waarbij 00000000-0000-0000-0000-0000000000 wordt vervangen door uw toepassings-id.

Klaar! U hebt een toepassing geregistreerd. Zie de onderstaande voorbeelden voor het verkrijgen en valideren van tokens.

Ondersteunde machtigingsbereiken

Machtigingnaam	Beschrijving	Ondersteunde acties
Investigation.read	Alle ondersteunde acties uitvoeren voor activiteiten en waarschuwingen, behalve waarschuwingen sluiten. IP-bereiken weergeven, maar niet toevoegen, bijwerken of verwijderen. Voer alle acties voor entiteiten uit.	Lijst met activiteiten, ophalen, feedback Lijst met waarschuwingen, ophalen, markeren als gelezen/ongelezen Lijst met entiteiten, ophalen, ophalen, ophalen van structuur Subnetlijst
Investigation.manage	Voer alle investigation.read-acties uit naast het beheren van waarschuwingen en IP-bereiken.	Lijst met activiteiten, ophalen, feedback Lijst met waarschuwingen, ophalen, markeren als gelezen/ongelezen, sluiten Lijst met entiteiten, ophalen, ophalen, ophalen van structuur Subnetlijst, maken/bijwerken/verwijderen
Discovery.read	Alle ondersteunde acties uitvoeren voor activiteiten en waarschuwingen, behalve waarschuwingen sluiten. Detectierapporten en -categorieën weergeven.	Lijst met waarschuwingen, ophalen, markeren als gelezen/ongelezen Detectielijstrapporten, lijstrapportcategorieën
Discovery.manage	Discovery.read-machtigingen Waarschuwingen sluiten, detectiebestanden uploaden en blokscripts genereren	Lijst met waarschuwingen, ophalen, markeren als gelezen/ongelezen, sluiten Detectielijstrapporten, lijstrapportcategorieën Detectiebestand uploaden, blokscript genereren
Instellingen.read	IP-bereiken weergeven.	Subnetlijst
Instellingen.manage	IP-bereiken weergeven en beheren.	Subnetlijst, maken/bijwerken/verwijderen

Een toegangstoken opvragen

Zie de zelfstudie Microsoft Entra voor meer informatie over Microsoft Entra-tokens.

PowerShell gebruiken

# 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

C# gebruiken

De volgende code is getest met NuGet Microsoft.Identity.Client 4.47.2.

Maak een nieuwe consoletoepassing.
Installeer NuGet Microsoft.Identity.Client.
Voeg het volgende toe:
```
using Microsoft.Identity.Client;
```

Kopieer en plak de volgende code in uw app (vergeet niet om de drie variabelen bij te werken: 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;

Python gebruiken

Zie Microsoft Authentication Library (MSAL) voor Python.

Curl gebruiken

Notitie

In de volgende procedure wordt ervan uitgegaan dat Curl voor Windows al op uw computer is geïnstalleerd.

Open een opdrachtprompt en stel CLIENT_ID in op uw Azure-toepassings-id.
Stel CLIENT_SECRET in op uw Azure-toepassingsgeheim.
Stel TENANT_ID in op de Azure-tenant-id van de klant die uw app wil gebruiken voor toegang tot Defender voor Cloud Apps.
Voer de volgende opdracht uit:

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

U krijgt een antwoord in het volgende formulier:

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

Het token valideren

Zorg ervoor dat u het juiste token hebt:

Kopieer en plak het token dat u in de vorige stap in JWT hebt gekregen om het te decoderen.
Controleer of u een rolclaim krijgt met de gewenste machtigingen
In de volgende afbeelding ziet u een gedecodeerd token dat is verkregen uit een app met machtigingen voor alle Microsoft Defender voor Cloud Apps-rollen:

Image of token validation.

Het token gebruiken om toegang te krijgen tot Microsoft Defender voor Cloud Apps-API

Kies de API die u wilt gebruiken. Zie Defender voor Cloud Apps-API's voor meer informatie.
Stel de autorisatieheader in de HTTP-aanvraag in die u naar Bearer {token} verzendt (Bearer is het autorisatieschema).
De verlooptijd van het token is één uur. U kunt meer dan één aanvraag met hetzelfde token verzenden.

Hier volgt een voorbeeld van het verzenden van een aanvraag om een lijst met waarschuwingen op te halen met 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

Zie ook

API-tokens beheren