Delen via

Toegang tot Microsoft Defender for Cloud Apps met toepassingscontext

  • Artikel

Op deze pagina wordt beschreven hoe u een toepassing maakt om programmatische toegang te krijgen tot Defender for Cloud Apps zonder een gebruiker. Als u programmatische toegang nodig hebt tot Defender for 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 for Cloud Apps maakt veel van de gegevens en acties beschikbaar via een set programmatische API's. Met deze API's kunt u werkstromen automatiseren en innoveren op basis van Defender for Cloud Apps mogelijkheden. Voor de API-toegang is OAuth2.0-verificatie vereist. Zie OAuth 2.0-autorisatiecodestroom voor meer informatie.

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

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

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

Een app maken voor Defender for Cloud Apps

  1. Registreer in de Microsoft Entra-beheercentrum een nieuwe toepassing. Zie Quickstart: Een toepassing registreren bij de Microsoft Entra-beheercentrum voor meer informatie.

  2. Als u wilt dat uw app toegang krijgt tot Defender for Cloud Apps en deze machtiging 'Alle waarschuwingen lezen' wilt toewijzen, selecteert u OP de toepassingspagina API-machtigingen Toevoegen machtigings-API's>>diemijn organisatie gebruikt>, typt u Microsoft Cloud App Security en selecteert u vervolgens Microsoft Cloud App Security.

    Opmerking

    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 heet het product nu Defender for Cloud Apps.

    Schermopname van het toevoegen van machtigingen.

    • Selecteer Toepassingsmachtigingen>Investigation.Read en selecteer vervolgens Machtigingen toevoegen.

      Schermopname van het toevoegen van app-machtigingen.

      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.

  3. Selecteer Beheerderstoestemming verlenen.

    Opmerking

    Telkens wanneer u een machtiging toevoegt, moet u Beheerderstoestemming verlenen selecteren om de nieuwe machtiging van kracht te laten worden.

    Schermopname van het verlenen van beheerdersmachtigingen.

  4. Als u een geheim wilt toevoegen aan de toepassing, selecteert u Certificaten & geheimen, selecteert u Nieuw clientgeheim, voegt u een beschrijving toe aan het geheim en selecteert u vervolgens Toevoegen.

    Opmerking

    Nadat u Toevoegen hebt geselecteerd, selecteert u de gegenereerde geheime waarde kopiëren. U kunt deze waarde niet meer ophalen nadat u deze hebt verlaten.

    Schermopname van het maken van een app-sleutel.

  5. 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).

    Schermopname van de gemaakte app-id.

  6. Alleen voor Microsoft Defender for Cloud Apps-partners. Stel uw app in op multitenant (beschikbaar in alle tenants na toestemming). Dit is vereist voor apps van derden (bijvoorbeeld als u een app maakt die is bedoeld om te worden uitgevoerd 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 maakt voor uw eigen gebruik die alleen met uw eigen gegevens communiceert). Uw app instellen op multitenant:

    • Ga naar Verificatie en voeg toe https://portal.azure.com als omleidings-URI.

    • Selecteer onder aan de pagina onder Ondersteunde accounttypen de toestemming voor accounts in een organisatiemaptoepassing voor uw app met meerdere tenants.

    U moet uw toepassing goedkeuren in elke tenant waar u deze wilt gebruiken. Dit komt doordat uw toepassing communiceert Defender for Cloud Apps namens uw klant.

    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 000000000-0000-0000-00000-0000000000000 wordt vervangen door uw toepassings-id.

Gereed! U hebt een toepassing geregistreerd. Bekijk hieronder voorbeelden voor het verkrijgen en valideren van tokens.

Ondersteunde machtigingsbereiken

Machtigingsnaam Beschrijving Ondersteunde acties
Investigation.read Alle ondersteunde acties uitvoeren voor activiteiten en waarschuwingen, behalve waarschuwingen voor sluiten.
IP-bereiken weergeven, maar niet toevoegen, bijwerken of verwijderen.

Alle entiteitenacties uitvoeren.		 Activiteitenlijst, ophalen, feedback
Lijst met waarschuwingen, ophalen, markeren als gelezen/ongelezen
Entiteitenlijst, ophalen, structuur ophalen
Subnetlijst
Investigation.manage Voer alle investigation.read-acties uit naast het beheren van waarschuwingen en IP-bereiken. Activiteitenlijst, ophalen, feedback
Lijst met waarschuwingen, ophalen, markeren als gelezen/ongelezen, sluiten
Entiteitenlijst, ophalen, structuur ophalen
Subnetlijst, maken/bijwerken/verwijderen
Discovery.read Alle ondersteunde acties uitvoeren voor activiteiten en waarschuwingen, behalve waarschuwingen voor 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
Settings.manage IP-bereiken weergeven en beheren. Subnetlijst, maken/bijwerken/verwijderen

Een toegangstoken ophalen

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.

  1. Maak een nieuwe consoletoepassing.

  2. Installeer NuGet Microsoft.Identity.Client.

  3. Voeg het volgende toe:

    using Microsoft.Identity.Client;

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

Python gebruiken

Zie Microsoft Authentication Library (MSAL) voor Python.

Curl gebruiken

Opmerking

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

  1. Open een opdrachtprompt en stel CLIENT_ID in op uw Azure-toepassings-id.
  2. Stel CLIENT_SECRET in op uw Azure-toepassingsgeheim.
  3. Stel TENANT_ID in op de Azure-tenant-id van de klant die uw app wil gebruiken voor toegang tot Defender for Cloud Apps.
  4. 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:

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

Schermopname van tokenvalidatie.

Het token gebruiken voor toegang tot Microsoft Defender for Cloud Apps API

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

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