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

  • Articolo

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

  1. Accedere ad Azure con un account utente con il ruolo Global Amministrazione istrator.

  2. Passare a Microsoft Entra ID> Registrazioni app> Nuova registrazione.

    Image of Microsoft Azure and navigation to application registration.

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

    • Nome: immettere un nome di applicazione significativo, che verrà 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 Entra di Microsoft.

      Se l'app è stata registrata come microsoft entra-only a tenant singolo, è possibile aggiornarla in modo che sia multi-tenant di 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 è mappata agli account Microsoft Entra multi-tenant e Microsoft personali.

      Se l'app è stata registrata come account Microsoft Entra multi-tenant e microsoft 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, ossia Web o Client pubblico (per dispositivi mobili e 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.

  4. 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.

      add permission.

    • Scegliere Autorizzazioni>delegate Indagine.Lettura> selezionare Aggiungi autorizzazioni

      application permissions.

    • 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.

      Image of Grant permissions.

  5. Annotare l'ID applicazione e l'ID tenant:

    • Nella pagina dell'applicazione passare a Panoramica e copiare le informazioni seguenti:

      Image of created app id.

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 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, il nome utente e la password per acquisire un token.

    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:

    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 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

Vedi anche