Creare un'app per accedere a Microsoft Defender per endpoint senza un utente

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 senza un utente. Se è necessario l'accesso a livello di codice a Defender per endpoint per conto di un utente, vedere Ottenere l'accesso con il contesto utente. Se non si è certi dell'accesso necessario, vedere 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 di innovare in base alle funzionalità di 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 Defender per endpoint.

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

Importante

Microsoft consiglia di usare i ruoli con il minor numero di autorizzazioni. Ciò consente di migliorare la sicurezza per l'organizzazione. Amministratore globale è un ruolo con privilegi elevati che deve essere limitato agli scenari di emergenza quando non è possibile usare un ruolo esistente.

Creare un'app

1. Accedere al portale di Azure con un utente con il ruolo Amministratore globale.

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

   

3. Nel modulo di registrazione scegliere un nome per l'applicazione e quindi selezionare Registra.

4. Per consentire all'app di accedere a Defender per endpoint e assegnarle l'autorizzazione "Leggi tutti gli avvisi", nella pagina dell'applicazione selezionare Autorizzazioni> APIAggiungiAPI di autorizzazione > usate >dall'organizzazione, digitare WindowsDefenderATP e quindi selezionare WindowsDefenderATP.

   Nota

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

   

   Selezionare Autorizzazioni applicazione>Alert.Read.All e quindi Aggiungi autorizzazioni.

   

5. Selezionare le autorizzazioni appropriate. Read All Alerts è solo un esempio. Ecco alcuni esempi:

   • Per eseguire query avanzate, selezionare l'autorizzazione Run advanced queries .
   • Per isolare un dispositivo, selezionare l'autorizzazione Isolate machine .
   • Per determinare l'autorizzazione necessaria, vedere la sezione Autorizzazioni nell'API da chiamare.

6. Selezionare Concedi consenso.

   Nota

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

   

7. Per aggiungere un segreto all'applicazione, selezionare Certificati & segreti, aggiungere una descrizione al segreto e quindi selezionare Aggiungi.

   Nota

   Dopo aver selezionato Aggiungi, selezionare copiare il valore del segreto generato. Non sarà possibile recuperare questo valore dopo l'uscita.

   

8. Annotare l'ID applicazione e l'ID tenant. Nella pagina dell'applicazione passare a Panoramica e copiare quanto segue.

   

9. Solo per i partner Microsoft Defender per endpoint. Impostare l'app in modo che sia multi-tenant (disponibile in tutti i tenant dopo il consenso). Questa operazione è necessaria per le app di terze parti, ad esempio se si crea un'app che deve essere eseguita nel tenant di più clienti. Questa operazione non è necessaria se si crea un servizio che si vuole eseguire solo nel tenant, ad esempio se si crea un'applicazione per il proprio utilizzo che interagirà solo con i propri dati. Per impostare l'app in modo che sia multi-tenant, seguire questa procedura:

   1. Passare a Autenticazione e aggiungere https://portal.azure.com come URI di reindirizzamento.

   2. Nella parte inferiore della pagina, in Tipi di account supportati selezionare account in qualsiasi consenso dell'applicazione directory aziendale per l'app multi-tenant.

      È necessario che l'applicazione venga approvata in ogni tenant in cui si intende usarla. Questo perché l'applicazione interagisce con Defender per endpoint per conto del cliente.

      L'utente (o il cliente se si sta scrivendo un'app di terze parti) deve selezionare il collegamento di consenso e approvare l'app. Il consenso deve essere eseguito con un utente con privilegi amministrativi in Active Directory.

      Il collegamento di consenso è formato come segue:

      https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true
      

      Dove 00000000-0000-0000-0000-000000000000 viene sostituito con l'ID applicazione.

Fatto! È stata registrata correttamente un'applicazione. Vedere gli esempi seguenti per l'acquisizione e la convalida dei token.

Ottenere un token di accesso

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

Usare PowerShell.

# This script acquires the App Context Token and stores it in the variable $token for later use in the script.
# Paste your Tenant ID, App ID, and App Secret (App key) into the indicated quotes below.

$tenantId = '' ### Paste your tenant ID here
$appId = '' ### Paste your Application ID here
$appSecret = '' ### Paste your Application key here

$sourceAppIdUri = 'https://api.securitycenter.microsoft.com/.default'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/v2.0/token"
$authBody = [Ordered] @{
    scope = "$sourceAppIdUri"
    client_id = "$appId"
    client_secret = "$appSecret"
    grant_type = 'client_credentials'
}
$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token
$token

Usare C#:

Il codice seguente è stato testato con NuGet Microsoft.Identity.Client 3.19.8.

Importante

Il pacchetto NuGet Microsoft.IdentityModel.Clients.ActiveDirectory e azure AD Authentication Library (ADAL) sono stati deprecati. Dal 30 giugno 2020 non sono state aggiunte nuove funzionalità. Si consiglia vivamente di eseguire l'aggiornamento. Per altri dettagli, vedere la guida alla migrazione .

1. Creare una nuova applicazione console.

2. Installare NuGet Microsoft.Identity.Client.

3. Aggiungere quanto segue:

   using Microsoft.Identity.Client;
   

4. Copiare e incollare il codice seguente nell'app (non dimenticare di aggiornare le tre variabili: tenantId, appId, appSecret):

   string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here
   string appId = "11111111-1111-1111-1111-111111111111"; // Paste your own app ID here
   string appSecret = "22222222-2222-2222-2222-222222222222"; // Paste your own app secret here for a test, and then store it in a safe place! 
   const string authority = "https://login.microsoftonline.com";
   const string audience = "https://api.securitycenter.microsoft.com";
   
   IConfidentialClientApplication myApp = ConfidentialClientApplicationBuilder.Create(appId).WithClientSecret(appSecret).WithAuthority($"{authority}/{tenantId}").Build();
   
   List<string> scopes = new List<string>() { $"{audience}/.default" };
   
   AuthenticationResult authResult = myApp.AcquireTokenForClient(scopes).ExecuteAsync().GetAwaiter().GetResult();
   
   string token = authResult.AccessToken;
   

Usare Python

Vedere Ottenere un token con Python.

Usare Curl

Nota

La procedura seguente presuppone che Curl per Windows sia già installato nel computer.

1. Aprire un prompt dei comandi e impostare l'ID CLIENT_ID applicazione di Azure.

2. Impostare sul CLIENT_SECRET segreto dell'applicazione Azure.

3. Impostare sull'ID TENANT_ID tenant di Azure del cliente che vuole usare l'app per accedere a Defender per endpoint.

4. Eseguire il comando qui riportato:

   curl -i -X POST -H "Content-Type:application/x-www-form-urlencoded" -d "grant_type=client_credentials" -d "client_id=%CLIENT_ID%" -d "scope=https://securitycenter.onmicrosoft.com/windowsatpservice/.default" -d "client_secret=%CLIENT_SECRET%" "https://login.microsoftonline.com/%TENANT_ID%/oauth2/v2.0/token" -k
   

   Si ottiene una risposta simile al frammento di codice seguente:

   {"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn <truncated> aWReH7P0s0tjTBX8wGWqJUdDA"}
   

Convalidare il token

Assicurarsi di avere il token corretto:

1. Copiare e incollare il token ottenuto nel passaggio precedente in JWT per decodificarlo.

2. Verificare di ottenere un'attestazione dei ruoli con le autorizzazioni desiderate.

   Nell'immagine seguente è possibile visualizzare un token decodificato acquisito da un'app con autorizzazioni per tutti i ruoli di Microsoft Defender per endpoint:

   

Usare il token per accedere all'API Microsoft Defender per endpoint

1. Scegliere l'API da usare. Per altre informazioni, vedere Api di Defender per endpoint supportate.

2. Impostare l'intestazione di autorizzazione nella http richiesta inviata a Bearer {token} (Bearer è lo schema di autorizzazione).

3. L'ora di scadenza del token è di un'ora. È possibile inviare più richieste con lo stesso token.

Di seguito è riportato un 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

• Accedere a API di Microsoft Defender per endpoint
• Accedere a Microsoft Defender per endpoint per conto di un utente

Consiglio

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