Accedere all'API Microsoft Defender for Cloud Apps con il contesto utente

  • Articolo
  • 7 minuti per la lettura

Nota

  • Sono stati rinominati Microsoft Cloud App Security. Viene ora chiamato Microsoft Defender for Cloud Apps. Nelle prossime settimane verranno aggiornate le schermate e le istruzioni qui e nelle pagine correlate. Per altre informazioni sulla modifica, vedere questo annuncio. Per altre informazioni sulla ridenominazione recente dei servizi di sicurezza Microsoft, vedere il blog di Microsoft Ignite Security.

  • Microsoft Defender for Cloud Apps fa ora parte di Microsoft 365 Defender. Il portale di Microsoft 365 Defender consente agli amministratori della sicurezza di eseguire le attività di sicurezza in un'unica posizione. In questo modo si semplificano i flussi di lavoro e si aggiungeranno le funzionalità degli altri servizi Microsoft 365 Defender. Microsoft 365 Defender sarà la sede principale per il monitoraggio e la gestione della sicurezza tra identità, dati, dispositivi, app e infrastruttura Microsoft. Per altre informazioni su queste modifiche, vedere Microsoft Defender for Cloud Apps in Microsoft 365 Defender.

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

Se è necessario accedere a livello di codice Microsoft Defender for Cloud Apps senza un utente, fare riferimento a Access Microsoft Defender for Cloud Apps con il contesto dell'applicazione.

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

Microsoft Defender for Cloud Apps 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à di Microsoft Defender for Cloud Apps. L'accesso all'API richiede l'autenticazione OAuth2.0. Per altre informazioni, vedere Codice di autorizzazione OAuth 2.0 Flow.

In generale, è necessario seguire questa procedura per usare le API:

  • Creare un'applicazione Azure Active Directory (Azure AD)
  • 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 Azure AD, ottenere un token di accesso per Microsoft Defender for Cloud Apps e convalidare il token.

Nota

Quando si accede Microsoft Defender for Cloud Apps'API per conto di un utente, è necessaria l'autorizzazione dell'applicazione e l'autorizzazione utente corrette. Se non si ha familiarità con le autorizzazioni utente per Microsoft Defender for Cloud Apps, 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.

Creare un'app

  1. Accedere ad Azure con un account utente con il ruolo di amministratore globale .

  2. Passare a Azure Active Directory>Registrazioni app>Nuova registrazione.

    Image of Microsoft Azure and navigation to application registration

  3. Nella pagina Registra un'applicazione visualizzata immettere 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 account 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 solo a un tenant singolo di Azure AD.

      È 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 è costituita da account Microsoft personali e multi-tenant Azure AD.
      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 solo a multi-tenant Azure AD.

      Se l'app è stata registrata come solo tenant singolo di Azure AD, è possibile aggiornarla in modo che sia multi-tenant di Azure AD e tornare a tenant singolo tramite il riquadro Autenticazione .
      Account in qualsiasi directory organizzativa e account Microsoft personali Selezionare questa opzione per includere il set più ampio possibile di clienti.

      Questa opzione esegue il mapping ad account Microsoft personali e multi-tenant Azure AD.

      Se l'app è stata registrata come account Microsoft multi-tenant e personali di Azure AD, non è possibile modificarla nell'interfaccia utente. Per modificare i tipi di account supportati è necessario usare l'editor del manifesto dell'applicazione.

    • URI di reindirizzamento (facoltativo): selezionare il tipo di app che si sta creando, client Web o pubblico (desktop per dispositivi mobili & ) 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 eseguita 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 Azure AD per restituire le risposte dei 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 Microsoft Defender for Cloud Apps e assegnarla l'autorizzazione "Read alerts":

    • Nella pagina dell'applicazione selezionare Autorizzazioni> API Aggiungi API diautorizzazione>usate dall'organizzazione per> 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 visualizzarlo. Assicurarsi di digitare questo nome, anche se il prodotto è ora denominato app 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 è interessati a 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 dell'autorizzazione Descrizione Azioni supportate
Indagine.read Eseguire tutte le azioni supportate per attività e avvisi, ad eccezione degli avvisi di chiusura.
Visualizzare gli intervalli IP ma non aggiungere, aggiornare o eliminare.

Eseguire tutte le azioni delle entità.		 Elenco attività, recupero, feedback
Elenco avvisi, recupero, contrassegno come letto/non letto
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 attività, recupero, feedback
Elenco avvisi, recupero, contrassegno come lettura/non letto, chiusura
Elenco di entità, recupero, albero di recupero
Elenco di subnet, creazione/aggiornamento/eliminazione
Discovery.read Eseguire tutte le azioni supportate per attività e avvisi, ad eccezione degli avvisi di chiusura.
Elencare i report e le categorie di individuazione.		 Elenco avvisi, recupero, contrassegno come letto/non letto
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/non letto, 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 di subnet, creazione/aggiornamento/eliminazione

Ottenere un token di accesso

Per altre informazioni sui token di Azure AD, vedere Esercitazione su Azure AD

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 di Microsoft Defender for Cloud Apps

  • Scegliere l'API da usare. Per altre informazioni, vedere API Defender per il cloud Apps.

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

Vedere anche