Accesso ai partner tramite le API di Microsoft Defender per endpoint
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
- 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:
Creare un'applicazione Microsoft Entra multi-tenant.
Ottenere l'autorizzazione (consenso) da parte dell'amministratore del cliente affinché l'applicazione possa accedere alle risorse di Defender per endpoint necessarie.
Ottenere un token di accesso usando questa applicazione.
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
Accedere al tenant di Azure con un utente con ruolo amministratore globale .
Passare a Registrazioni >dell'appMicrosoft Entra ID>Nuova registrazione.
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
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.
Richiedere autorizzazioni API
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 .
Nell'esempio seguente viene usata l'autorizzazione Leggi tutti gli avvisi :
Scegliere Autorizzazioni applicazione>Alert.Read.All> selezionare aggiungi autorizzazioni
Selezionare Concedi consenso
- Ogni volta che si aggiunge l'autorizzazione, è necessario selezionare su Concedi consenso per rendere effettiva la nuova autorizzazione.
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!
Annotare l'ID applicazione:
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.
Inoltre, dovrai chiedere al cliente l'ID tenant e salvarlo per un uso futuro quando acquisirai il token.
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.
Creare una nuova applicazione console.
Installare NuGet Microsoft.Identity.Client.
Aggiungere il codice seguente usando:
using Microsoft.Identity.Client;
Questo codice è stato testato con NuGet
Microsoft.Identity.Client
.Copiare/incollare il codice seguente nell'applicazione (non dimenticare di aggiornare le tre variabili:
tenantId
,appId
eappSecret
).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
Aprire una finestra di comando.
Impostare l'ID
CLIENT_ID
applicazione di Azure.Impostare sul
CLIENT_SECRET
segreto dell'applicazione Azure.Impostare sull'ID
TENANT_ID
tenant di Azure del cliente che vuole usare l'applicazione per accedere all'applicazione Microsoft Defender per endpoint.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.
Copiare/incollare in JWT il token ottenuto nel passaggio precedente per decodificarlo.
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:
L'attestazione "tid" è l'ID tenant a cui appartiene il token.
Usare il token per accedere all'API Microsoft Defender per endpoint
Scegliere l'API da usare. Per altre informazioni, vedere Api supportate di Microsoft Defender per endpoint.
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
- 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.