Accedere all'API delle app Microsoft Defender per il cloud con il contesto utente

Articolo
08/19/2024

Questa pagina descrive come creare un'applicazione per ottenere l'accesso a livello di codice alle app di Defender per il cloud per conto di un utente.

Se è necessario l'accesso a livello di codice Microsoft Defender per il cloud App senza un utente, fare riferimento a Access Microsoft Defender per il cloud Apps with application context (Accedere alle app Microsoft Defender per il cloud con il contesto dell'applicazione).

Se non si è certi dell'accesso necessario, leggere la pagina Introduzione.

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 di innovare in base alle funzionalità delle app di Microsoft 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

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

Nota

Quando si accede Microsoft Defender per il cloud'API delle app per conto di un utente, è necessaria l'autorizzazione corretta per l'applicazione e l'autorizzazione utente. Se non si ha familiarità con le autorizzazioni utente per le app Microsoft Defender per il cloud, vedere Gestire l'accesso amministratore.

Suggerimento

Se si dispone dell'autorizzazione per eseguire un'azione nel portale, si dispone dell'autorizzazione per eseguire l'azione nell'API.

Crea un'app

Nell'interfaccia di amministrazione di Microsoft Entra registrare una nuova applicazione. Per altre informazioni, vedere Avvio rapido: Registrare un'applicazione con l'interfaccia di amministrazione di Microsoft Entra.

Quando viene visualizzata la pagina Registra un'applicazione, inserire le informazioni di registrazione dell'applicazione:

Nome : immettere un nome di applicazione significativo visualizzato agli utenti dell'app.

Tipi di account supportati: selezionare gli account che dovranno essere supportati dall'applicazione.

Tipi di conto supportati	Descrizione
Account solo in questa directory organizzativa	Selezionare questa opzione se si sta creando un'applicazione line-of-business. Questa opzione non è disponibile se l'applicazione non viene registrata in una directory. Questa opzione esegue il mapping a Microsoft Entra-only single-tenant. È l'opzione predefinita a meno che non si registri l'app all'esterno di una directory. Nei casi in cui l'app viene registrata all'esterno di una directory, l'impostazione predefinita è Microsoft Entra multi-tenant e account Microsoft personali.
Account in qualsiasi directory organizzativa	Selezionare questa opzione se si preferisce includere tutti i clienti aziendali o di istituti di istruzione. Questa opzione esegue il mapping a un multi-tenant solo Microsoft Entra.This option maps to a Microsoft Entra-only multitenant. Se l'app è stata registrata come microsoft entra-only a tenant singolo, è possibile aggiornarla in modo che sia multi-tenant Microsoft Entra e di nuovo a tenant singolo tramite il riquadro Autenticazione .
Account in qualsiasi directory organizzativa e account Microsoft personali	Selezionare questa opzione per il più ampio gruppo di clienti. Questa opzione esegue il mapping agli account Microsoft Entra multi-tenant e personali microsoft. Se l'app è stata registrata come account Microsoft Entra multi-tenant e personali, non è possibile modificarla nell'interfaccia utente. Invece, è necessario utilizzare l'editor del manifesto dell'applicazione per modificare i tipi di account supportati.

URI di reindirizzamento (facoltativo): selezionare il tipo di app che si sta creando, **Web o Client pubblico (mobile & desktop) e quindi immettere l'URI di reindirizzamento (o l'URL di risposta) per l'applicazione.
- Per le applicazioni Web, specificare l'URL di base dell'app. Ad esempio, http://localhost:31544 potrebbe essere l'URL per un'app Web in esecuzione sul computer locale. Gli utenti possono usare questo URL per accedere a un'applicazione client Web.
- Per le applicazioni client pubbliche, specificare l'URI usato da Microsoft Entra ID per restituire le risposte del token. Immettere un valore specifico dell'applicazione, ad esempio myapp://auth.
Per esempi specifici per le applicazioni Web o per le applicazioni native, vedere le guide introduttive.

Al termine, selezionare Registra.

Consentire all'applicazione di accedere alle app di Microsoft Defender per il cloud e assegnargli l'autorizzazione "Leggi avvisi":
- Nella pagina dell'applicazione selezionare Autorizzazioni>API Aggiungi api di autorizzazione>che l'organizzazione usa> il tipo 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.
- Scegliere Autorizzazioni>delegate Indagine.Lettura> selezionare Aggiungi autorizzazioni
- Nota importante: selezionare le autorizzazioni pertinenti. Investigation.Read è solo un esempio. Per altri ambiti di autorizzazione, vedere Ambiti di autorizzazione supportati
  - Per determinare l'autorizzazione necessaria, visualizzare la sezione Autorizzazioni nell'API che si vuole chiamare.
- Selezionare Concedi consenso amministratore
  
  Nota: ogni volta che si aggiunge l'autorizzazione è necessario selezionare Concedi consenso amministratore per rendere effettiva la nuova autorizzazione.
Annotare l'ID applicazione e l'ID tenant:
- Nella pagina dell'applicazione passare a Panoramica e copiare le informazioni seguenti:

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
Settings.read	Elencare gli intervalli IP.	Elenco di subnet
Settings.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 Esercitazione su Microsoft Entra

Uso di C#

Copiare/incollare la classe seguente nell'applicazione.
Usare il metodo AcquireUserTokenAsync con l'ID applicazione, l'ID tenant e l'autenticazione acquisiscono un token.

Nota

Mentre l'esempio di codice seguente illustra come acquisire un token usando il flusso di nome utente e password, Microsoft consiglia di usare flussi di autenticazione più sicuri in un ambiente di produzione.

namespace MDA
{
    using System.Net.Http;
    using System.Text;
    using System.Threading.Tasks;
    using Newtonsoft.Json.Linq;

    public static class MDAUtils
    {
        private const string Authority = "https://login.microsoftonline.com";

        private const string MDAId = "05a65629-4c1b-48c1-a78b-804c4abdd4af";
        private const string Scope = "Investigation.read";

        public static async Task<string> AcquireUserTokenAsync(string username, string password, string appId, string tenantId)
        {
            using (var httpClient = new HttpClient())
            {
                var urlEncodedBody = $"scope={MDAId}/{Scope}&client_id={appId}&grant_type=password&username={username}&password={password}";

                var stringContent = new StringContent(urlEncodedBody, Encoding.UTF8, "application/x-www-form-urlencoded");

                using (var response = await httpClient.PostAsync($"{Authority}/{tenantId}/oauth2/token", stringContent).ConfigureAwait(false))
                {
                    response.EnsureSuccessStatusCode();

                    var json = await response.Content.ReadAsStringAsync().ConfigureAwait(false);

                    var jObject = JObject.Parse(json);

                    return jObject["access_token"].Value<string>();
                }
            }
        }
    }
}

Convalidare il token

Verificare di avere ottenuto un token corretto:

Copiare/incollare in JWT il token ottenuto nel passaggio precedente per decodificarlo
Verificare di ottenere un'attestazione "scp" con le autorizzazioni dell'app desiderate
Nello screenshot seguente è possibile visualizzare un token decodificato acquisito dall'app nell'esercitazione:

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 Authorization nella richiesta HTTP inviata a "Bearer {token}" (Bearer è lo schema di autorizzazione)
L'ora di scadenza del token è di 1 ora (è possibile inviare più di una richiesta con lo stesso token)

Esempio di invio di una richiesta per ottenere un elenco di avvisi tramite 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

Condividi tramite