Creare un'app per accedere a Microsoft Defender XDR senza un utente
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 senza un utente definito, ad esempio se si sta creando un daemon o un servizio in background.
Se è necessario l'accesso a livello di codice a Microsoft Defender XDR per conto di uno o più utenti, vedere Creare un'app per accedere Microsoft Defender XDR API per conto di un utente e Creare un'app con accesso partner alle API Microsoft Defender XDR. 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 Microsoft Defender XDR.
Questo articolo illustra come:
- Creare un'applicazione Microsoft Entra
- Ottenere un token di accesso a Microsoft Defender XDR
- Convalidare il token.
Accedere ad Azure.
Passare a Microsoft Entra ID>Registrazioni app>Nuova registrazione.
Nel modulo scegliere un nome per l'applicazione e quindi selezionare Registra.
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.
Suggerimento
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.
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".
Selezionare Concedi consenso amministratore. Ogni volta che si aggiunge un'autorizzazione, è necessario selezionare Concedi consenso amministratore per renderla effettiva.
Per aggiungere un segreto all'applicazione, selezionare Certificati & segreti, aggiungere una descrizione al segreto e quindi selezionare Aggiungi.
Suggerimento
Dopo aver selezionato Aggiungi, selezionare copiare il valore del segreto generato. Non sarà possibile recuperare il valore del segreto dopo l'uscita.
Registrare l'ID applicazione e l'ID tenant in un punto sicuro. Sono elencati in Panoramica nella pagina dell'applicazione.
Solo per Microsoft Defender XDR partner: seguire queste istruzioni per l'accesso ai partner tramite le API Microsoft Defender XDR, impostare l'app su più tenant, in modo che possa essere disponibile in tutti i tenant dopo aver ricevuto il consenso dell'amministratore. L'accesso ai partner è necessario per le app di terze parti, ad esempio se si crea un'app che deve essere eseguita in più tenant dei clienti. Non è necessario se si crea un servizio che si vuole eseguire solo nel tenant, ad esempio un'applicazione per il proprio utilizzo che interagirà solo con i propri dati. Per impostare l'app come multi-tenant:
Passare a Autenticazione e aggiungere https://portal.azure.com come URI di reindirizzamento.
Nella parte inferiore della pagina, in Tipi di account supportati selezionare account in qualsiasi consenso dell'applicazione directory aziendale per l'app multi-tenant.
Poiché l'applicazione interagisce con Microsoft Defender XDR per conto degli utenti, deve essere approvata per ogni tenant in cui si intende usarla.
L'amministratore di Active Directory per ogni tenant deve selezionare il collegamento di consenso e approvare l'app.
Il collegamento di consenso ha la struttura 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.
Fatto! È stata registrata correttamente un'applicazione. Vedere gli esempi seguenti per l'acquisizione e la convalida dei token.
Per altre informazioni sui token Microsoft Entra, vedere l'esercitazione Microsoft Entra.
Importante
Anche se gli esempi in questa sezione incoraggiano a incollare i valori dei segreti a scopo di test, non è mai consigliabile codificare i segreti in un'applicazione in esecuzione nell'ambiente di produzione. Una terza parte potrebbe usare il segreto per accedere alle risorse. È possibile proteggere i segreti dell'app usando Azure Key Vault. Per un esempio pratico di come proteggere l'app, vedere Gestire i segreti nelle app server con Azure Key Vault.
# 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, such as the Azure Key Vault!
$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
Nota
Il codice seguente è stato testato con Nuget Microsoft.Identity.Client 3.19.8.
Importante
Il pacchetto NuGet Microsoft.IdentityModel.Clients.ActiveDirectory e Autenticazione di Azure AD 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 .
Creare una nuova applicazione console.
Installare NuGet Microsoft.Identity.Client.
Aggiungere la riga seguente:
using Microsoft.Identity.Client;
Copiare e incollare il codice seguente nell'app (non dimenticare di aggiornare le tre variabili:
tenantId
,clientId
,appSecret
):csharp 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;
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"]
Nota
Curl è preinstallato in Windows 10, versioni 1803 e successive. Per altre versioni di Windows, scaricare e installare lo strumento direttamente dal sito Web ufficiale curl.
Aprire un prompt dei comandi e impostare CLIENT_ID sul proprio ID applicazione di Azure.
Impostare CLIENT_SECRET sul segreto dell'applicazione Azure.
Impostare TENANT_ID sull'ID tenant di Azure del cliente che vuole usare l'app per accedere a Microsoft Defender XDR.
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://api.security.microsoft.com/.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"}
Copiare e incollare il token nel sito Web di convalida del token JSON, JWT, per decodificarlo.
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.All
autorizzazioni ,Incidents.ReadWrite.All
eAdvancedHunting.Read.All
:
Scegliere l'API da usare (eventi imprevisti o ricerca avanzata). Per altre informazioni, vedere API Microsoft Defender XDR supportate.
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.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();
- Panoramica delle API Microsoft Defender XDR
- Accedere alle API Microsoft Defender XDR
- Creare un'applicazione 'Hello world'
- Creare un'app per accedere alle API Microsoft Defender XDR per conto di un utente
- Creare un'app con accesso partner multi-tenant alle API Microsoft Defender XDR
- 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
Suggerimento
Per saperne di più, Visitare la community di Microsoft Security nella Tech Community: Tech Community di Microsoft Defender XDR.