Creare un'app per accedere a Microsoft Threat Protection senza un utenteCreate an app to access Microsoft Threat Protection without a user

Importante

Microsoft 365 Defender, il nuovo nome di Microsoft Threat Protection.Welcome to Microsoft 365 Defender, the new name for Microsoft Threat Protection. Per ulteriori informazioni, vedere questo e altri aggiornamenti qui.Read more about this and other updates here. Verrà aggiornato il nome nei prodotti e nei documenti nel prossimo futuroWe'll be updating names in products and in the docs in the near future

Si applica a:Applies to:

  • Microsoft Threat ProtectionMicrosoft Threat Protection

Importante

Alcune informazioni si riferiscono al prodotto prerilasciato che può essere modificato in modo sostanziale prima che venga rilasciato commercialmente.Some information relates to prereleased product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.Microsoft makes no warranties, express or implied, with respect to the information provided here.

In questa pagina viene descritto come creare un'applicazione per ottenere l'accesso programmatico a Microsoft Threat Protection senza un utente.This page describes how to create an application to get programmatic access to Microsoft Threat Protection without a user. Se è necessario l'accesso a livello di programmazione a Microsoft Threat Protection per conto di un utente, vedere Get Access with user context.If you need programmatic access to Microsoft Threat Protection on behalf of a user, see Get access with user context. Se non si è certi di quale accesso è necessario, vedere Introduzione.If you are not sure which access you need, see Get started.

Microsoft Threat Protection espone gran parte dei suoi dati e delle sue azioni tramite un insieme di API programmatiche.Microsoft Threat Protection exposes much of its data and actions through a set of programmatic APIs. Tali API consentono di automatizzare i flussi di lavoro e di innovare in base alle funzionalità di protezione dalle minacce di Microsoft.Those APIs will help you automate work flows and innovate based on Microsoft Threat Protection capabilities. L'accesso API richiede l'autenticazione OAuth 2.0.The API access requires OAuth2.0 authentication. Per ulteriori informazioni, vedere il flusso del codice di autorizzazione OAuth 2,0.For more information, see OAuth 2.0 Authorization Code Flow.

In generale, è necessario eseguire la procedura seguente per utilizzare le API:In general, you'll need to take the following steps to use the APIs:

  • Creare un'applicazione Azure Active Directory (Azure AD).Create an Azure Active Directory (Azure AD) application.
  • Ottenere un token di accesso utilizzando l'applicazione.Get an access token using this application.
  • Utilizzare il token per accedere all'API di Microsoft Threat Protection.Use the token to access Microsoft Threat Protection API.

In questo articolo viene illustrato come creare un'applicazione Azure AD, ottenere un token di accesso a Microsoft Threat Protection e convalidare il token.This article explains how to create an Azure AD application, get an access token to Microsoft Threat Protection, and validate the token.

Creare un'appCreate an app

  1. Accedere a Azure con un utente che ha il ruolo di amministratore globale .Log on to Azure with a user that has the Global Administrator role.

  2. Passare a registrazione delle app di Azure Active Directory > App registrations > nuova registrazione.Navigate to Azure Active Directory > App registrations > New registration.

    Immagine di Microsoft Azure e spostamento alla registrazione dell'applicazione

  3. Nel modulo di registrazione scegliere un nome per l'applicazione e quindi fare clic su registra.In the registration form, choose a name for your application, and then select Register.

  4. Per consentire all'app di accedere a Microsoft Threat Protection e assegnargli le autorizzazioni, nella pagina dell'applicazione selezionare autorizzazioni API > Aggiungi autorizzazioneAPI > l'organizzazione utilizza >, digitare Microsoft Threat Protectione quindi selezionare Microsoft Threat Protection.To enable your app to access Microsoft Threat Protection and assign it permissions, on your application page, select API Permissions > Add permission > APIs my organization uses >, type Microsoft Threat Protection, and then select Microsoft Threat Protection.

    Nota

    Microsoft Threat Protection non viene visualizzato nell'elenco originale.Microsoft Threat Protection does not appear in the original list. È necessario iniziare a scrivere il nome nella casella di testo per visualizzarlo.You need to start writing its name in the text box to see it appear.

    Immagine dell'accesso API e della selezione dell'API

    • Selezionare Autorizzazioni applicazione > scegliere le autorizzazioni rilevanti per lo scenario, ad esempio, Incident. Read. All, quindi selezionare Aggiungi autorizzazioni.Select Application permissions > Choose the relevant permissions for your scenario, e.g. Incident.Read.All, and then select Add permissions.

    Immagine dell'accesso API e della selezione dell'API

    Nota

    È necessario selezionare le autorizzazioni rilevanti per lo scenario, ' Leggi tutti gli incidenti ' è solo un esempio.You need to select the relevant permissions for your scenario, 'Read all incidents' is just an example. Per determinare le autorizzazioni necessarie, consultare la sezione autorizzazioni nell'API che si desidera chiamare.To determine which permission you need, please look at the Permissions section in the API you are interested to call.

  5. Selezionare Concedi consenso.Select Grant consent.

    Nota

    Ogni volta che si aggiunge un'autorizzazione, è necessario selezionare Concedi consenso per rendere effettive le nuove autorizzazioni.Every time you add a permission, you must select Grant consent for the new permission to take effect.

    Immagine delle autorizzazioni di concessione

  6. Per aggiungere un segreto all'applicazione, selezionare certificati & segreti, aggiungere una descrizione al segreto e quindi fare clic su Aggiungi.To add a secret to the application, select Certificates & secrets, add a description to the secret, and then select Add.

    Nota

    Dopo aver selezionato Aggiungi, selezionare copia il valore segreto generato.After you select Add, select copy the generated secret value. Non sarà possibile recuperare questo valore dopo l'uscita.You won't be able to retrieve this value after you leave.

    Immagine del tasto Crea app

  7. Annotare l'ID dell'applicazione e l'ID del tenant.Write down your application ID and your tenant ID. Nella pagina applicazione passare a Panoramica e copiare quanto segue.On your application page, go to Overview and copy the following.

    Immagine dell'ID app creato

  8. Solo per i partner di Microsoft Threat Protection.For Microsoft Threat Protection Partners only. Seguire le istruzioniriportate di seguito.Follow the instructions here. Impostare l'app come multi-tenanted (disponibile in tutti i tenant dopo il consenso).Set your app to be multi-tenanted (available in all tenants after consent). Questo è necessario per le app di terze parti (ad esempio, se si crea un'app che deve essere eseguita in più tenant dei clienti).This is required for third-party apps (for example, if you create an app that is intended to run in multiple customers' tenant). Non è necessario se si crea un servizio che si desidera eseguire solo nel tenant (ad esempio, se si crea un'applicazione per il proprio utilizzo che interagirà solo con i propri dati).This is not required if you create a service that you want to run in your tenant only (for example, if you create an application for your own usage that will only interact with your own data). Per impostare l'app come multi-tenant:To set your app to be multi-tenanted:

    • Andare a autenticazionee aggiungere https://portal.azure.com come URI di Reindirizzamento.Go to Authentication, and add https://portal.azure.com as the Redirect URI.

    • Nella parte inferiore della pagina, in tipi di account supportati, selezionare gli account in qualsiasi autorizzazione dell'applicazione directory organizzativa per l'app multi-tenant.On the bottom of the page, under Supported account types, select the Accounts in any organizational directory application consent for your multi-tenant app.

    È necessario che l'applicazione venga approvata in ogni tenant in cui si intende utilizzarla.You need your application to be approved in each tenant where you intend to use it. Ciò è dovuto al fatto che l'applicazione interagisce sulla protezione dalle minacce Microsoft per conto del cliente.This is because your application interacts Microsoft Threat Protection on behalf of your customer.

    Se si sta scrivendo un'app di terze parti, l'utente o il cliente deve selezionare il collegamento di consenso e approvare l'app.You (or your customer if you are writing a third-party app) need to select the consent link and approve your app. Il consenso dovrebbe essere effettuato con un utente che dispone di privilegi amministrativi in Active Directory.The consent should be done with a user who has administrative privileges in Active Directory.

    Il collegamento di consenso è formato come indicato di seguito:The consent link is formed as follows:

    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 dell'applicazione.Where 00000000-0000-0000-0000-000000000000 is replaced with your application ID.

Fatto!Done! La registrazione di un'applicazione è stata completata correttamente.You have successfully registered an application! Vedere gli esempi riportati di seguito per l'acquisizione e la convalida dei token.See examples below for token acquisition and validation.

Ottenere un token di accessoGet an access token

Per ulteriori informazioni sui token di Azure AD, vedere l' esercitazione di Azure ad.For more details on Azure AD tokens, see the Azure AD tutorial.

Utilizzo di PowerShellUse 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.security.microsoft.com'
$oAuthUri = "https://login.windows.net/$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

Utilizzare C#:Use C#:

Il codice seguente è stato testato con NuGet Microsoft. IdentityModel. clients. ActiveDirectory 3.19.8.The following code was tested with Nuget Microsoft.IdentityModel.Clients.ActiveDirectory 3.19.8.

  1. Creare una nuova applicazione console.Create a new console application.

  2. Installare NuGet Microsoft. IdentityModel. clients. ActiveDirectory.Install Nuget Microsoft.IdentityModel.Clients.ActiveDirectory.

  3. Aggiungere gli elementi seguenti:Add the following:

    using Microsoft.IdentityModel.Clients.ActiveDirectory;
    
  4. Copiare e incollare il codice seguente nell'app (non dimenticare di aggiornare le tre variabili: tenantId, appId, appSecret ):Copy and paste the following code in your app (don't forget to update the three variables: 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.windows.net";
    const string wdatpResourceId = "https://api.security.microsoft.com";
    
    AuthenticationContext auth = new AuthenticationContext($"{authority}/{tenantId}/");
    ClientCredential clientCredential = new ClientCredential(appId, appSecret);
    AuthenticationResult authenticationResult = auth.AcquireTokenAsync(wdatpResourceId, clientCredential).GetAwaiter().GetResult();
    string token = authenticationResult.AccessToken;
    

Utilizzare PythonUse Python

import json
import urllib.request
import urllib.parse

tenantId = '00000000-0000-0000-0000-000000000000' # Paste your own tenant ID here
appId = '11111111-1111-1111-1111-111111111111' # Paste your own app ID here
appSecret = '22222222-2222-2222-2222-222222222222' # Paste your own app secret here

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

resourceAppIdUri = 'https://api.securitycenter.windows.com'

body = {
    'resource' : resourceAppIdUri,
    'client_id' : appId,
    '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"]

Utilizzo di curlUse Curl

Nota

La procedura seguente presuppone che curl per Windows sia già installato nel computer in uso.The following procedure assumes that Curl for Windows is already installed on your computer.

  1. Aprire una finestra del prompt dei comandi e impostare CLIENT_ID sull'ID dell'applicazione di Azure.Open a command prompt, and set CLIENT_ID to your Azure application ID.
  2. Impostare CLIENT_SECRET per l'applicazione di Azure segreta.Set CLIENT_SECRET to your Azure application secret.
  3. Impostare TENANT_ID sull'ID tenant di Azure del cliente che desidera utilizzare l'app per accedere a Microsoft Threat Protection.Set TENANT_ID to the Azure tenant ID of the customer that wants to use your app to access Microsoft Threat Protection.
  4. Eseguire il comando seguente:Run the following command:
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 otterrà una risposta nel formato seguente:You will get an answer in the following form:

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

Convalidare il tokenValidate the token

Assicurarsi di aver ottenuto il token corretto:Ensure that you got the correct token:

  1. Copiare e incollare il token ottenuto nel passaggio precedente in JWT per decodificarlo.Copy and paste the token you got in the previous step into JWT in order to decode it.
  2. Convalidare che si ottiene un'attestazione di ' ruoli ' con le autorizzazioni desiderateValidate that you get a 'roles' claim with the desired permissions
  3. Nell'immagine seguente, è possibile visualizzare un token decodificato acquisito da un'app con Incidents.Read.All Incidents.ReadWrite.All e AdvancedHunting.Read.All autorizzazioni:In the following image, you can see a decoded token acquired from an app with Incidents.Read.All, Incidents.ReadWrite.All and AdvancedHunting.Read.All permissions:

Immagine della convalida dei token

Utilizzare il token per accedere all'API di Microsoft Threat ProtectionUse the token to access Microsoft Threat Protection API

  1. Scegliere l'API che si desidera utilizzare.Choose the API you want to use. Per ulteriori informazioni, vedere API di Microsoft Threat Protection supportate.For more information, see Supported Microsoft Threat Protection APIs.

  2. Impostare l'intestazione di autorizzazione nella richiesta HTTP inviata a "portatore {token}" (il portatore è lo schema di autorizzazione).Set the authorization header in the http request you send to "Bearer {token}" (Bearer is the authorization scheme).

  3. La data di scadenza del token è di un'ora.The expiration time of the token is one hour. È possibile inviare più di una richiesta con lo stesso token.You can send more then one request with the same token.

Di seguito è riportato un esempio di invio di una richiesta per ottenere un elenco di operazioni non consentite tramite C#:The following is an example of sending a request to get a list of incidents using 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();

    // Do something useful with the response