Usare le API di Microsoft Defender per endpoint

Si applica a:

• Microsoft Defender per endpoint Piano 1
• Microsoft Defender per endpoint Piano 2
• Microsoft Defender for Business

Importante

Le funzionalità di ricerca avanzata non sono incluse in Defender per le aziende.

Se si desidera provare Microsoft Defender per endpoint, iscriversi a una versione di valutazione gratuita.

Nota

Se si è un cliente del governo degli Stati Uniti, usare gli URI elencati in Microsoft Defender per endpoint per i clienti del governo degli Stati Uniti.

Consiglio

Per ottenere prestazioni migliori, è possibile usare il server più vicino alla posizione geografica:

• us.api.security.microsoft.com
• eu.api.security.microsoft.com
• uk.api.security.microsoft.com
• au.api.security.microsoft.com
• swa.api.security.microsoft.com

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

Se è necessario accedere a livello di codice a Microsoft Defender per endpoint senza un utente, vedere Accedere a Microsoft Defender per endpoint con il contesto dell'applicazione.

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

Microsoft Defender per endpoint espone gran parte dei dati e delle azioni tramite un set di API programmatiche. Queste API consentono di automatizzare i flussi di lavoro e innovare in base alle funzionalità di Microsoft Defender per endpoint. 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 Di Defender per endpoint

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

Nota

Quando si accede all'API Microsoft Defender per endpoint per conto di un utente, sono necessarie le autorizzazioni dell'applicazione e dell'utente corrette. Se non si ha familiarità con le autorizzazioni utente in Microsoft Defender per endpoint, vedere Gestire l'accesso al portale usando il controllo degli accessi in base al ruolo.

Consiglio

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 al portale di Azure.

2. Passare a Registrazioni >dell'appMicrosoft Entra ID>Nuova registrazione.

   

3. 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 viene mappata al tenant singolo di Microsoft Entra.This option maps to Microsoft Entra-only single-tenant. Questa opzione è 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 multi-tenant e account Microsoft personali.
     Account in qualsiasi directory dell'organizzazione	Selezionare questa opzione se si vuole indirizzare tutti i clienti aziendali e didattici. Questa opzione è mappata a un multi-tenant solo Entra di Microsoft. Se l'app è stata registrata come tenant singolo di Microsoft Entra, è possibile aggiornarla in modo che sia multi-tenant di Microsoft Entra e tornare a un singolo tenant tramite il pannello Autenticazione .
     Account in qualsiasi directory organizzativa e account Microsoft personali	Selezionare questa opzione per selezionare il set più ampio di clienti. Questa opzione è mappata agli account Microsoft microsoft multi-tenant e personali. Se l'app è stata registrata come account Microsoft multi-tenant e personali di Microsoft, 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, il client Web o 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.

4. Consentire all'applicazione di accedere a Microsoft Defender per endpoint e assegnarle l'autorizzazione "Avvisi di lettura":

   • Nella pagina dell'applicazione selezionare Autorizzazioni> APIAggiungi API di autorizzazione>che l'organizzazione usa> il tipo WindowsDefenderATP e selezionare in WindowsDefenderATP.

     Nota

     WindowsDefenderATP non viene visualizzato nell'elenco originale. Iniziare a scrivere il nome nella casella di testo per visualizzarlo.

     

   • Scegliere Autorizzazioni delegate>Avviso.Leggere> selezionare Aggiungi autorizzazioni.

     

   Importante

   Selezionare le autorizzazioni pertinenti. Gli avvisi di lettura sono solo un esempio.

   Ad esempio:

   • Per eseguire query avanzate, selezionare l'autorizzazione Esegui query avanzate .

   • Per isolare un dispositivo, selezionare Isola autorizzazione computer .

   • Per determinare l'autorizzazione necessaria, vedere la sezione Autorizzazioni nell'API che si vuole chiamare.

   • Selezionare Concedi consenso.

     Nota

     Ogni volta che si aggiunge l'autorizzazione, è necessario selezionare su Concedi consenso per rendere effettiva la nuova autorizzazione.

     

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

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

   

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 WindowsDefenderATP
  {
      using System.Net.Http;
      using System.Text;
      using System.Threading.Tasks;
      using Newtonsoft.Json.Linq;
  
      public static class WindowsDefenderATPUtils
      {
          private const string Authority = "https://login.microsoftonline.com";
  
          private const string WdatpResourceId = "https://api.securitycenter.microsoft.com";
  
          public static async Task<string> AcquireUserTokenAsync(string username, string password, string appId, string tenantId)
          {
              using (var httpClient = new HttpClient())
              {
                  var urlEncodedBody = $"resource={WdatpResourceId}&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 per endpoint

• Scegliere l'API che si vuole usare : API Microsoft Defender per endpoint supportate.

• 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://api.securitycenter.microsoft.com/api/alerts");
  
  request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
  
  var response = httpClient.SendAsync(request).GetAwaiter().GetResult();
  
  // Do something useful with the response
  

Vedere anche

• API di Microsoft Defender per endpoint
• Accedere a Microsoft Defender per endpoint con il contesto dell'applicazione

Consiglio

Per saperne di più, Collaborare con la community di Microsoft Security nella community tech: Microsoft Defender per endpoint Tech Community.