Accedere alle app Microsoft Defender per il cloud con il contesto dell'applicazione

Articolo
01/23/2024

Questa pagina descrive come creare un'applicazione per ottenere l'accesso a livello di codice alle app di Defender per il cloud senza un utente. Se è necessario l'accesso a livello di codice per Defender per il cloud App per conto di un utente, vedere Ottenere l'accesso con il contesto utente. Se non si è certi dell'accesso necessario, vedere la pagina Gestione dei token API.

Microsoft Defender per il cloud App espone gran parte dei dati e delle azioni tramite un set di API a livello di codice. Queste API consentono di automatizzare i flussi di lavoro e l'innovazione in base alle funzionalità delle app Defender per il cloud. L'accesso all'API richiede l'autenticazione OAuth2.0. Per altre informazioni, vedere Flusso del codice di autorizzazione OAuth 2.0.

In generale, è necessario eseguire i passaggi seguenti per usare le API:

Creare un'applicazione Microsoft Entra.
Ottenere un token di accesso usando questa applicazione.
Usare il token per accedere all'API delle app di Defender per il cloud.

Questo articolo illustra come creare un'applicazione Microsoft Entra, ottenere un token di accesso per Microsoft Defender per il cloud App e convalidare il token.

Crea un'app

Accedere ad Azure con un utente con il ruolo Global Amministrazione istrator.
Passare a Microsoft Entra ID> Registrazioni app> Nuova registrazione.
Nel modulo di registrazione scegliere un nome per l'applicazione e quindi selezionare Registra.
Per consentire all'app di accedere alle app di Defender per il cloud e assegnarla l'autorizzazione "Leggi tutti gli avvisi", nella pagina dell'applicazione selezionare Autorizzazioni>API Aggiungi autorizzazione>usate dall'organizzazione>, digitare Microsoft Cloud App Security e quindi selezionare Microsoft Cloud App Security.

Nota

Microsoft Cloud App Security non viene visualizzato nell'elenco originale. Iniziare a scrivere il nome nella casella di testo per visualizzarla. Assicurarsi di digitare questo nome, anche se il prodotto è ora denominato app di Defender per il cloud.
- Selezionare Autorizzazioni>applicazione Investigation.Read e quindi selezionare Aggiungi autorizzazioni.
  
  È necessario selezionare le autorizzazioni pertinenti. Investigation.Read è solo un esempio. Per altri ambiti di autorizzazione, vedere Ambiti di autorizzazione supportati
  - Per determinare l'autorizzazione necessaria, esaminare la sezione Autorizzazioni nell'API che si vuole chiamare.
Seleziona Concedi consenso amministratore.

Nota

Ogni volta che si aggiunge un'autorizzazione, è necessario selezionare Concedi consenso amministratore per rendere effettiva la nuova autorizzazione.
Per aggiungere un segreto all'applicazione, selezionare Certificati e segreti, selezionare Nuovo segreto client, aggiungere una descrizione al segreto e quindi selezionare Aggiungi.

Nota

Dopo aver selezionato Aggiungi, selezionare Copia il valore del segreto generato. Non sarà possibile recuperare questo valore dopo l'uscita.
Annotare l'ID applicazione e l'ID tenant. Nella pagina dell'applicazione passare a Panoramica e copiare l'ID applicazione (client) e l'IDdirectory (tenant).
Solo per i partner di app di Microsoft Defender per il cloud. Impostare l'app su multi-tenant (disponibile in tutti i tenant dopo il consenso). Questa operazione è necessaria per le app di terze parti, ad esempio se si crea un'app destinata a essere eseguita nel tenant di più clienti. Questa operazione non è necessaria se si crea un servizio che si vuole eseguire solo nel tenant, ad esempio se si crea un'applicazione per il proprio utilizzo che interagirà solo con i propri dati. Per impostare l'app su multi-tenant:
- Passare ad Autenticazione e aggiungere https://portal.azure.com come URI di reindirizzamento.
- Nella parte inferiore della pagina, in Tipi di account supportati, selezionare il consenso account in qualsiasi applicazione della directory organizzativa per l'app multi-tenant.
È necessario che l'applicazione venga approvata in ogni tenant in cui si intende usarla. Ciò è dovuto al fatto che l'applicazione interagisce Defender per il cloud App per conto del cliente.

Se stai scrivendo un'app di terze parti, devi selezionare il collegamento di consenso e approvare l'app. Il consenso deve essere eseguito con un utente con privilegi amministrativi in Active Directory.

Il collegamento di consenso viene formato nel modo seguente:
```
https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true
```
Dove 00000000-0000-0000-0000-0000000000000 viene sostituito con l'ID applicazione.

La procedura è stata completata. È stata registrata correttamente un'applicazione. Vedere gli esempi seguenti per l'acquisizione e la convalida dei token.

Ambiti di autorizzazione supportati

Nome autorizzazione	Descrizione	Azioni supportate
Indagine.read	Eseguire tutte le azioni supportate per le attività e gli avvisi, ad eccezione della chiusura degli avvisi. Visualizzare gli intervalli IP, ma non aggiungere, aggiornare o eliminare. Eseguire tutte le azioni delle entità.	Elenco di attività, recupero, feedback Elenco avvisi, recupero, contrassegno come lettura/lettura Elenco di entità, recupero, albero di recupero Elenco di subnet
Investigation.manage	Eseguire tutte le azioni investigation.read oltre a gestire gli avvisi e gli intervalli IP.	Elenco di attività, recupero, feedback Elenco avvisi, recupero, contrassegno come lettura/lettura, chiusura Elenco di entità, recupero, albero di recupero Elenco subnet, creazione/aggiornamento/eliminazione
Discovery.read	Eseguire tutte le azioni supportate per le attività e gli avvisi, ad eccezione della chiusura degli avvisi. Elencare i report e le categorie di individuazione.	Elenco avvisi, recupero, contrassegno come lettura/lettura Report elenco di individuazione, categorie di report elenco
Discovery.manage	Autorizzazioni Discovery.read Chiudere gli avvisi, caricare i file di individuazione e generare script di blocco	Elenco avvisi, recupero, contrassegno come lettura/lettura, chiusura Report elenco di individuazione, categorie di report elenco Caricamento di file di individuazione, generazione di script di blocco
Impostazioni.read	Elencare gli intervalli IP.	Elenco di subnet
Impostazioni.manage	Elencare e gestire gli intervalli IP.	Elenco subnet, creazione/aggiornamento/eliminazione

Ottenere un token di accesso

Per altre informazioni sui token di Microsoft Entra, vedere l'esercitazione su Microsoft Entra.

Utilizzare 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

Usare C#

Il codice seguente è stato testato con NuGet Microsoft.Identity.Client 4.47.2.

Creare una nuova applicazione console.
Installare NuGet Microsoft.Identity.Client.
Aggiungere quanto segue:
```
using Microsoft.Identity.Client;
```

Copiare e incollare il codice seguente nell'app (non dimenticare di aggiornare le tre variabili): 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;

Uso di Python

Vedere Microsoft Authentication Library (MSAL) per Python.

Usare Curl

Nota

La procedura seguente presuppone che Curl per Windows sia già installato nel computer.

Aprire un prompt dei comandi e impostare CLIENT_ID sul proprio ID applicazione Azure.
Impostare CLIENT_edizione Standard CRET sul segreto dell'applicazione Azure.
Impostare TENANT_ID sull'ID tenant di Azure del cliente che vuole usare l'app per accedere alle app Defender per il cloud.
Esegui questo comando:

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

Si otterrà una risposta nel formato seguente:

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

Convalidare il token

Assicurarsi di avere ottenuto il token corretto:

Copiare e incollare il token ottenuto nel passaggio precedente in JWT per decodificarlo.
Verificare di ottenere un'attestazione "ruoli" con le autorizzazioni desiderate
Nell'immagine seguente è possibile visualizzare un token decodificato acquisito da un'app con autorizzazioni per tutti i ruoli delle app Microsoft Defender per il cloud:

Image of token validation.

Usare il token per accedere all'API delle app di Microsoft Defender per il cloud

Scegliere l'API da usare. Per altre informazioni, vedere Defender per il cloud API delle app.
Impostare l'intestazione di autorizzazione nella richiesta HTTP inviata a "Bearer {token}" (Bearer è lo schema di autorizzazione).
L'ora di scadenza del token è un'ora. È possibile inviare più richieste con lo stesso token.

Di seguito è riportato un esempio di invio di una richiesta per ottenere un elenco di avvisi usando 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

Vedi anche

Gestione dei token API