Creare un'app per accedere alle API XDR di Microsoft Defender per conto di un utente

  • Articolo

Si applica a:

  • Microsoft Defender XDR

Importante

Alcune informazioni fanno riferimento alle caratteristiche del prodotto prima del rilascio, e possono essere modificate sostanzialmente prima della distribuzione al pubblico. Microsoft non fornisce alcuna garanzia, esplicita o implicita, in relazione alle informazioni contenute in questo documento.

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

Se è necessario l'accesso a livello di codice a Microsoft Defender XDR senza un utente definito (ad esempio, se si sta scrivendo un'app in background o un daemon), vedere Creare un'app per accedere a Microsoft Defender XDR senza un utente. Se è necessario fornire l'accesso a più tenant, ad esempio se si sta servendo un'organizzazione di grandi dimensioni o un gruppo di clienti, vedere Creare un'app con accesso ai partner alle API XDR di Microsoft Defender. Se non si è certi del tipo di accesso necessario, vedere Introduzione.

Microsoft Defender XDR 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 usare le funzionalità di Microsoft Defender XDR. Questo 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 queste API:

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

Questo articolo illustra come:

  • Creare un'applicazione Microsoft Entra
  • Ottenere un token di accesso a Microsoft Defender XDR
  • Convalidare il token

Nota

Quando si accede all'API XDR di Microsoft Defender per conto di un utente, sono necessarie le autorizzazioni dell'applicazione e dell'utente corrette.

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 ad Azure come utente con il ruolo Amministratore globale .

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

    Opzione Nuova registrazione nel riquadro Gestisci nel portale di Azure

  3. Nel modulo scegliere un nome per l'applicazione e immettere le informazioni seguenti per l'URI di reindirizzamento, quindi selezionare Registra.

    Riquadro di registrazione dell'applicazione nel portale di Azure

  4. Nella pagina dell'applicazione selezionare Autorizzazioni> APIAggiungi API di autorizzazione>usate dall'organizzazione>, digitare Microsoft Threat Protection e selezionare Microsoft Threat Protection. L'app può ora accedere a Microsoft Defender XDR.

    Consiglio

    Microsoft Threat Protection è un nome precedente per Microsoft Defender XDR e non verrà visualizzato nell'elenco originale. È necessario iniziare a scrivere il nome nella casella di testo per visualizzarlo.

    Riquadro API dell'organizzazione nel portale di Microsoft Defender

    • Scegliere Autorizzazioni delegate. Scegliere le autorizzazioni pertinenti per lo scenario, ad esempio Incident.Read, e quindi selezionare Aggiungi autorizzazioni.

      Riquadro Autorizzazioni delegate nel portale di Microsoft Defender

    Nota

    È necessario selezionare le autorizzazioni pertinenti per lo scenario. Leggere tutti gli eventi imprevisti è solo un esempio. Per determinare l'autorizzazione necessaria, vedere la sezione Autorizzazioni nell'API da chiamare.

    Ad esempio, per eseguire query avanzate, selezionare l'autorizzazione 'Esegui query avanzate'. per isolare un dispositivo, selezionare l'autorizzazione "Isola computer".

  5. Selezionare Concedi consenso amministratore. Ogni volta che si aggiunge un'autorizzazione, è necessario selezionare Concedi consenso amministratore per renderla effettiva.

    Riquadro di concessione del consenso dell'amministratore nel portale di Microsoft Defender

  6. Registrare l'ID applicazione e l'ID tenant in un punto sicuro. Sono elencati in Panoramica nella pagina dell'applicazione.

    Riquadro Panoramica nel portale di Microsoft Defender

Ottenere un token di accesso

Per altre informazioni sui token di Microsoft Entra, vedere l'esercitazione di Microsoft Entra.

Ottenere un token di accesso per conto di un utente tramite PowerShell

Usare la libreria MSAL.PS per acquisire i token di accesso con autorizzazioni delegate. Eseguire i comandi seguenti per ottenere il token di accesso per conto di un utente:

Install-Module -Name MSAL.PS # Install the MSAL.PS module from PowerShell Gallery

$TenantId = " " # Paste your directory (tenant) ID here.
$AppClientId="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # Paste your application (client) ID here.

$MsalParams = @{
   ClientId = $AppClientId
   TenantId = $TenantId
   Scopes   = 'https://graph.microsoft.com/User.Read.All','https://graph.microsoft.com/Files.ReadWrite','https://api.securitycenter.windows.com/AdvancedQuery.Read'
}

$MsalResponse = Get-MsalToken @MsalParams
$AccessToken  = $MsalResponse.AccessToken
 
$AccessToken # Display the token in PS console

Convalidare il token

  1. Copiare e incollare il token in JWT per decodificarlo.
  2. Assicurarsi che l'attestazione dei ruoli all'interno del token decodificato contenga le autorizzazioni desiderate.

Nell'immagine seguente è possibile visualizzare un token decodificato acquisito da un'app, con Incidents.Read.Allautorizzazioni , Incidents.ReadWrite.Alle AdvancedHunting.Read.All :

Sezione delle autorizzazioni nel riquadro Token decodificato nel portale di Microsoft Defender

Usare il token per accedere all'API XDR di Microsoft Defender

  1. Scegliere l'API da usare (eventi imprevisti o ricerca avanzata). Per altre informazioni, vedere API XDR di Microsoft Defender supportate.
  2. Nella richiesta HTTP che si sta per inviare impostare l'intestazione "Bearer" <token>di autorizzazione su , bearer come schema di autorizzazione e token come token convalidato.
  3. Il token scadrà entro un'ora. È possibile inviare più di una richiesta durante questo periodo con lo stesso token.

Nell'esempio seguente viene illustrato come inviare una richiesta per ottenere un elenco di eventi imprevisti tramite C#.

    var httpClient = new HttpClient();
    var request = new HttpRequestMessage(HttpMethod.Get, "https://api.security.microsoft.com/api/incidents");

    request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

    var response = httpClient.SendAsync(request).GetAwaiter().GetResult();

Consiglio

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