Create un'app con accesso partner alle API Microsoft Defender XDR

Si applica a:

• Microsoft Defender XDR

Questa pagina descrive come creare un'app Microsoft Entra con accesso a livello di codice a Microsoft Defender XDR, per conto degli utenti tra più tenant. Le app multi-tenant sono utili per gestire gruppi di utenti di grandi dimensioni.

Se è necessario l'accesso a livello di codice a Microsoft Defender XDR per conto di un singolo utente, vedere Create un'app per accedere alle API Microsoft Defender XDR per conto di un utente. Se è necessario l'accesso senza un utente definito in modo esplicito(ad esempio, se si sta scrivendo un'app in background o un daemon), vedere Create un'app per accedere a Microsoft Defender XDR senza un utente. 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:

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

Poiché questa app è multi-tenant, è necessario anche il consenso amministratore da ogni tenant per conto dei relativi utenti.

Questo articolo illustra come:

• Create un'applicazione Microsoft Entra multi-tenant
• Ottenere il consenso autorizzato dall'amministratore utente per consentire all'applicazione di accedere alla Microsoft Defender XDR di cui ha bisogno.
• Ottenere un token di accesso a Microsoft Defender XDR
• Convalidare il token

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 innovare in base alle funzionalità Microsoft Defender XDR. 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:

• Create un'applicazione Microsoft Entra multi-tenant.
• Ottenere l'autorizzazione (consenso) dell'amministratore utente per consentire all'applicazione di accedere alle risorse Microsoft Defender XDR necessarie.
• Ottenere un token di accesso usando questa applicazione.
• Usare il token per accedere all'API Microsoft Defender XDR.

La procedura seguente illustra come creare un'applicazione Microsoft Entra multi-tenant, ottenere un token di accesso per Microsoft Defender XDR e convalidare il token.

Create l'app multi-tenant

1. Accedere ad Azure come utente con il ruolo Amministratore globale .

2. Passare a Microsoft Entra ID>Registrazioni app>Nuova registrazione.

   

3. Nel modulo di registrazione:

   • Scegliere un nome per l'applicazione.
   • In Tipi di account supportati selezionare Account in qualsiasi directory organizzativa (qualsiasi directory Microsoft Entra) - Multi-tenant.
   • Compilare la sezione URI di reindirizzamento . Selezionare il tipo Web e assegnare l'URI di reindirizzamento come https://portal.azure.com.

   Al termine della compilazione del modulo, selezionare Registra.

   

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.

   

5. Selezionare Autorizzazioni dell’applicazione. Scegliere le autorizzazioni pertinenti per lo scenario, ad esempio Incident.Read.All, e quindi selezionare Aggiungi autorizzazioni.

   

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

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

   

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

   Consiglio

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

   

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

   

9. Aggiungere l'applicazione al tenant dell'utente.

   Poiché l'applicazione interagisce con Microsoft Defender XDR per conto degli utenti, deve essere approvata per ogni tenant in cui si intende usarla.

   Un amministratore globale del tenant dell'utente deve visualizzare 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
   

   Le cifre devono essere sostituite 00000000-0000-0000-0000-000000000000 con l'ID applicazione.

   Dopo aver fatto clic sul collegamento di consenso, accedere con l'amministratore globale del tenant dell'utente e concedere il consenso all'applicazione.

   

   Dovrai anche chiedere all'utente l'ID tenant. L'ID tenant è uno degli identificatori usati per acquisire i token di accesso.

• 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 Microsoft Entra, vedere l'esercitazione Microsoft Entra.

Ottenere un token di accesso tramite PowerShell

# This code gets the application context token and saves it to a file named "Latest-token.txt" under the current directory.

$tenantId = '' # Paste your directory (tenant) ID here
$clientId = '' # Paste your application (client) ID here
$appSecret = '' # Paste your own app secret here to test, then store it in a safe place!

$resourceAppIdUri = 'https://api.security.microsoft.com'
$oAuthUri = "https://login.windows.net/$tenantId/oauth2/token"

$authBody = [Ordered] @{
    resource = $resourceAppIdUri
    client_id = $clientId
    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

Ottenere un token di accesso usando C#

1. Create una nuova applicazione console.

2. Installare NuGet Microsoft.Identity.Client.

3. Aggiungere la riga seguente:

   using Microsoft.Identity.Client;
   

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

Ottenere un token di accesso con Python

import json
import urllib.request
import urllib.parse

tenantId = '' # Paste your directory (tenant) ID here
clientId = '' # Paste your application (client) ID here
appSecret = '' # Paste your own app secret here to test, then store it in a safe place, such as the Azure Key Vault!

url = "https://login.windows.net/%s/oauth2/token" % (tenantId)

resourceAppIdUri = 'https://api.security.microsoft.com'

body = {
    'resource' : resourceAppIdUri,
    'client_id' : clientId,
    'client_secret' : appSecret,
    'grant_type' : 'client_credentials'
}

data = urllib.parse.urlencode(body).encode("utf-8")

req = urllib.request.Request(url, data)
response = urllib.request.urlopen(req)
jsonResponse = json.loads(response.read())
aadToken = jsonResponse["access_token"]

Ottenere un token di accesso usando curl

1. Aprire un prompt dei comandi e impostare CLIENT_ID sul proprio ID applicazione di Azure.
2. Impostare CLIENT_SECRET sul segreto dell'applicazione Azure.
3. Impostare TENANT_ID sull'ID tenant di Azure dell'utente che vuole usare l'app per accedere a Microsoft Defender XDR.
4. Eseguire il comando riportato di seguito:

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

Una risposta riuscita avrà un aspetto simile al seguente:

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

Convalidare il token

1. Copiare e incollare il token nel sito Web di convalida del token JSON, 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 :

Usare il token per accedere all'API Microsoft Defender XDR

1. Scegliere l'API da usare (eventi imprevisti o ricerca avanzata). Per altre informazioni, vedere API Microsoft Defender XDR 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();

Articoli correlati

• Panoramica delle API Microsoft Defender XDR
• Accedere alle API Microsoft Defender XDR
• Create un'applicazione 'Hello world'
• Create un'app per accedere a Microsoft Defender XDR senza un utente
• Create un'app per accedere alle API Microsoft Defender XDR per conto di un utente
• Informazioni sui limiti e sulle licenze delle API
• Informazioni sui codici di errore
• Gestire i segreti nelle app server con Azure Key Vault
• Autorizzazione OAuth 2.0 per l'accesso utente e l'accesso api