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

Questa pagina descrive come creare un'applicazione per ottenere l'accesso a livello di codice a Defender for Cloud Apps per conto di un utente.

Se è necessario l'accesso a livello di codice Microsoft Defender for Cloud Apps senza un utente, fare riferimento a Access Microsoft Defender for Cloud Apps with application context (Accesso Microsoft Defender for Cloud Apps con 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 programmatiche. Queste API consentono di automatizzare i flussi di lavoro e di innovare in base alle funzionalità Microsoft Defender for Cloud Apps. L'accesso api richiede l'autenticazione OAuth2.0. Per altre informazioni, vedere Flusso del codice di autorizzazione OAuth 2.0.

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

• Creare un'applicazione Microsoft Entra
• Ottenere un token di accesso usando questa applicazione
• Usare il token per accedere all'API Defender for Cloud Apps

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

Creare un'app

1. Nel Interfaccia di amministrazione di Microsoft Entra registrare una nuova applicazione. Per altre informazioni, vedere Avvio rapido: Registrare un'applicazione con il Interfaccia di amministrazione di Microsoft Entra.

2. Quando viene visualizzata la pagina Registra un'applicazione , immettere 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 da supportare per l'applicazione.

     Tipi di account supportati	Descrizione
     Solo gli account in questa directory organizzativa	Selezionare questa opzione se si sta creando un'applicazione line-of-business (LOB). Questa opzione non è disponibile se non si registra l'applicazione in una directory. Questa opzione esegue il mapping a Microsoft Entra-only single-tenant. Questa è l'opzione predefinita, a meno che non si registri l'app all'esterno di una directory. Nei casi in cui l'app è registrata all'esterno di una directory, l'impostazione predefinita è Microsoft Entra account Microsoft multi-tenant e personali.
     Account in qualsiasi directory dell'organizzazione	Selezionare questa opzione se si vuole indirizzare tutti i clienti aziendali e didattici. Questa opzione esegue il mapping a un multi-tenant solo Microsoft Entra. Se l'app è stata registrata come tenant singolo solo Microsoft Entra, è possibile aggiornarla in modo che sia Microsoft Entra multi-tenant e tornare a un singolo tenant tramite il riquadro Autenticazione.
     Account in qualsiasi directory organizzativa e account Microsoft personali	Selezionare questa opzione per selezionare il set più ampio di clienti. Questa opzione è mappata a Microsoft Entra account Microsoft multi-tenant e personali. Se l'app è stata registrata come Microsoft Entra account Microsoft multi-tenant e personali, non è possibile modificarla nell'interfaccia utente. È invece necessario usare 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 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 di un'app Web in esecuzione nel computer locale. Gli utenti usano 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 myapp://authesempio .

     Per visualizzare esempi specifici per applicazioni Web o applicazioni native, vedere le guide introduttive.

     Al termine, selezionare Registra.

3. Consentire all'applicazione di accedere a Microsoft Defender for Cloud Apps e assegnarle l'autorizzazione "Avvisi di lettura":

   • Nella pagina dell'applicazione selezionare Autorizzazioni> APIAggiungi API di autorizzazione>usate> dall'organizzazione di 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 visualizzarlo. Assicurarsi di digitare questo nome, anche se il prodotto è ora chiamato Defender for Cloud Apps.

     

   • Scegliere Autorizzazioni delegate>Indagine.Leggere> 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, vedere 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.

     

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

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

     

Ambiti di autorizzazione supportati

Ottenere un token di accesso

Per altre informazioni sui token Microsoft Entra, vedere Microsoft Entra esercitazione

Uso di C#

• Copiare/incollare la classe seguente nell'applicazione.
• Usare il metodo AcquireUserTokenAsync con l'ID applicazione, l'ID tenant e l'autenticazione 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 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 Microsoft Defender for Cloud Apps

• Scegliere l'API da usare. Per altre informazioni, vedere DEFENDER FOR CLOUD APPS API.

• 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
  

Vedere anche

• Gestione dei token API
• flusso del codice di autorizzazione di Microsoft Identity Platform e OAuth 2.0