Condividi tramite


Accesso ai partner tramite le API di Microsoft Defender per endpoint

Si applica a:

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
  • ina.api.security.microsoft.com

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

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 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:

  1. Creare un'applicazione Microsoft Entra multi-tenant.

  2. Ottenere l'autorizzazione (consenso) da parte dell'amministratore del cliente affinché l'applicazione possa accedere alle risorse di Defender per endpoint necessarie.

  3. Ottenere un token di accesso usando questa applicazione.

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

La procedura seguente 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 l'app multi-tenant

  1. Accedere al tenant di Azure con un utente con ruolo amministratore globale .

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

    Riquadro di spostamento per la registrazione dell'applicazione

  3. Nel modulo di registrazione:

    • Scegliere un nome per l'applicazione.

    • Tipi di account supportati: account in qualsiasi directory dell'organizzazione.

    • URI di reindirizzamento - tipo: Web, URI: https://portal.azure.com

      Pagina di registrazione dell'applicazione partner di Microsoft Azure

  4. Consentire all'applicazione di accedere a Microsoft Defender per endpoint e assegnarla con il set minimo di autorizzazioni necessarie per completare l'integrazione.

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

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

      L'opzione Aggiungi un'autorizzazione

Richiedere autorizzazioni API

Per determinare l'autorizzazione necessaria, vedere la sezione Autorizzazioni nell'API da chiamare. Ad esempio:

Nell'esempio seguente viene usata l'autorizzazione Leggi tutti gli avvisi :

  1. Scegliere Autorizzazioni applicazione>Alert.Read.All> selezionare aggiungi autorizzazioni

    L'opzione che consente di aggiungere un'autorizzazione

  2. Selezionare Concedi consenso

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

    L'opzione che consente di concedere il consenso

  3. Aggiungere un segreto all'applicazione.

    • Selezionare Certificati & segreti, aggiungere una descrizione al segreto e selezionare Aggiungi.

    Dopo aver selezionato Aggiungi, assicurarsi di copiare il valore del segreto generato. Non sarai in grado di recuperarlo dopo che te ne andrai!

    La chiave di creazione dell'app

  4. Annotare l'ID applicazione:

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

      ID dell'applicazione di creazione

  5. Aggiungere l'applicazione al tenant del cliente.

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

    Un utente con amministratore globale del tenant del cliente deve selezionare il collegamento di consenso e approvare l'applicazione.

    Il collegamento di consenso è nel formato seguente:

    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 deve essere sostituito con l'ID applicazione.

    Dopo aver selezionato il collegamento di consenso, accedere come amministratore globale del tenant del cliente e concedere il consenso all'applicazione.

    Pulsante Accetta

    Inoltre, dovrai chiedere al cliente l'ID tenant e salvarlo per un uso futuro quando acquisirai il token.

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

Ottenere un esempio di token di accesso

Per ottenere il token di accesso per conto del cliente, usare l'ID tenant del cliente nelle acquisizioni di token seguenti.

Per altre informazioni sul token Microsoft Entra, vedere Esercitazione su Microsoft Entra.

Utilizzo di PowerShell

# That code gets the App Context Token and save it to a file named "Latest-token.txt" under the current directory
# Paste below your Tenant ID, App ID and App Secret (App key).

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

$resourceAppIdUri = 'https://api.securitycenter.microsoft.com'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
$authBody = [Ordered] @{
    resource = "$resourceAppIdUri"
    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
Out-File -FilePath "./Latest-token.txt" -InputObject $token
return $token

Uso di C#

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à. Per eseguire l'aggiornamento, vedere la guida alla migrazione.

  1. Creare una nuova applicazione console.

  2. Installare NuGet Microsoft.Identity.Client.

  3. Aggiungere il codice seguente usando:

     using Microsoft.Identity.Client;
    

    Questo codice è stato testato con NuGet Microsoft.Identity.Client.

  4. Copiare/incollare il codice seguente nell'applicazione (non dimenticare di aggiornare le tre variabili: tenantId, appIde 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;
    

Uso di Python

Vedere Ottenere un token con Python.

Uso di Curl

Nota

La procedura seguente suppone curl per Windows è già installato nel computer

  1. Aprire una finestra di comando.

  2. Impostare l'ID CLIENT_ID applicazione di Azure.

  3. Impostare sul CLIENT_SECRET segreto dell'applicazione Azure.

  4. Impostare sull'ID TENANT_ID tenant di Azure del cliente che vuole usare l'applicazione per accedere all'applicazione Microsoft Defender per endpoint.

  5. 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

Verificare di aver ricevuto un token corretto.

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

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

    Nello screenshot seguente è possibile visualizzare un token decodificato acquisito da un'applicazione con più autorizzazioni per Microsoft Defender per endpoint:

    Pagina di convalida del token

    L'attestazione "tid" è l'ID tenant a cui appartiene il token.

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

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

  2. Impostare l'intestazione Authorization nella richiesta Http inviata a Bearer {token} (Bearer è lo schema di autorizzazione). L'ora di scadenza del token è di un'ora (è possibile inviare più di una richiesta con lo stesso token).

    Ecco 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

Consiglio

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