Skapa en app för åtkomst till Microsoft Defender för slutpunkt utan en användare

Gäller för:

Vill du uppleva Microsoft Defender för Endpoint? Registrera dig för en kostnadsfri utvärderingsversion.

Anteckning

Om du är myndighetskund i USA kan du använda de URI:er som visas i Microsoft Defender för Slutpunkt för kunder inom myndigheter i USA.

Tips

För bättre prestanda kan du använda servern närmare din geografiska plats:

  • api-us.securitycenter.microsoft.com
  • api-eu.securitycenter.microsoft.com
  • api-uk.securitycenter.microsoft.com

På den här sidan beskrivs hur du skapar ett program för att få programtisk åtkomst till Defender för Endpoint utan en användare. Om du behöver programmeringsåtkomst till Defender för Endpoint åt en användare kan du gå till Få åtkomst med användarkontext. Om du inte är säker på vilken åtkomst du behöver kan du gå till Komma igång.

Microsoft Defender för slutpunkt visar mycket av dess data och åtgärder via en uppsättning programmässiga API:er. De HÄR API:erna hjälper dig att automatisera arbetsflöden och nyfikna baserat på Defender för Slutpunkt-funktioner. API-åtkomst kräver OAuth2.0-autentisering. Mer information finns i OAuth 2.0 auktoriseringskod för Flow.

I allmänhet måste du vidta följande steg för att använda API:er:

  • Skapa ett Azure Active Directory (Azure AD).
  • Hämta en åtkomsttoken med det här programmet.
  • Använd tokenet för att komma åt Defender för Endpoint API.

I den här artikeln förklaras hur du skapar ett Azure AD-program, hämtar en åtkomsttoken till Microsoft Defender för Endpoint och verifierar token.

Skapa en app

  1. Logga in på Azure med en användare som har rollen Global administratör.

  2. Gå till Azure Active Directory > Appregistreringar > Ny registrering.

    Bild av Microsoft Azure navigering till programregistrering.

  3. Välj ett namn på din ansökan i registreringsformuläret och välj sedan Registrera.

  4. Om du vill aktivera appen för att komma åt Defender för Slutpunkt och tilldela behörigheten Läs alla aviseringar väljer du API-behörigheter Lägg till behörighets-API:er som min organisation använder >, skriver > > WindowsDefenderATP och väljer sedan WindowsDefenderATP.

    Anteckning

    WindowsDefenderATP visas inte i den ursprungliga listan. Börja skriva namnet i textrutan så att det visas.

    lägg till behörighet.

    Välj Avisering om > programbehörigheter.Läs.Alla och välj sedan Lägg till behörigheter.

    appbehörighet.

    Du måste välja rätt behörighet. "Läs alla aviseringar" är bara ett exempel. Till exempel:

    • Om du vill köra avanceradefrågor väljer du behörigheten Kör avancerade frågor.
    • Om du vill isolera enenhet väljer du behörigheten "Isolera dator".
    • Du kan avgöra vilken behörighet du behöver i avsnittet Behörigheter i api:t som du vill anropa.
  5. Välj Bevilja medgivande.

    Anteckning

    Varje gång du lägger till en behörighet måste du välja Ge medgivande för att den nya behörigheten ska gälla.

    Bevilja behörigheter.

  6. Om du vill lägga till en hemligt i programmet väljer du Certifikat &, lägger till en beskrivning till hemligheten och väljer sedan Lägg till.

    Anteckning

    När du har valt Lägg till väljer du kopiera det genererade hemliga värdet. Du kommer inte att kunna hämta det här värdet när du har lämnat.

    Bild av skapa programnyckel.

  7. Skriv ned ditt program-ID och ditt klient-ID. Gå till Översikt på programsidan och kopiera följande.

    Bild av skapat program-ID.

  8. Endast för Microsoft Defender för slutpunktspartner. Ange att appen ska ha flera klientorganisationsklienter (tillgänglig i alla klientorganisationen efter medgivande). Detta krävs för appar från tredje part (till exempel om du skapar ett program som ska köras i flera kunders klientorganisation). Detta krävs inte om du skapar en tjänst som du bara vill köra i klientorganisationen (till exempel om du skapar ett program för din egen användning som bara kommer att interagera med dina egna data). Så här anger du att programmet ska ha flera klientorganisationsklienter:

    • Gå till Autentisering och lägg till https://portal.azure.com som Redirect URI.

    • Längst ned på sidan, under Kontotyper som stöds, väljer du Konton i ett organisationskatalogprograms medgivande för appen med flera innehavare.

    Du behöver att programmet ska godkännas i varje klientorganisation där du tänker använda det. Det beror på att ditt program interagerar Defender för Endpoint åt din kund.

    Du (eller kunden om du skriver en app från tredje part) måste välja länken för medgivande och godkänna appen. Medgivandet bör göras med en användare som har administratörsbehörighet i Active Directory.

    Medgivandelänken är utformad på följande sätt:

    https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true
    

    Där 00000000-0000-0000-0000-00000000000 ersätts med ditt program-ID.

Klart! Du har registrerat ett program! Se exempel nedan för insamling och validering av token.

Hämta en åtkomsttoken

Mer information om Azure AD-token finns i självstudiekursen om Azure AD.

Använda PowerShell

# This script acquires the App Context Token and stores it in the variable $token for later use in the script.
# Paste your Tenant ID, App ID, and App Secret (App key) into the indicated quotes below.

$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

Använd C#:

Följande kod testades med NuGet Microsoft.IdentityModel.Clients.ActiveDirectory 3.19.8.

  1. Skapa ett nytt konsolprogram.

  2. Installera NuGet Microsoft.IdentityModel.Clients.ActiveDirectory.

  3. Lägg till följande:

    using Microsoft.IdentityModel.Clients.ActiveDirectory;
    
  4. Kopiera och klistra in följande kod i programmet (glöm inte att uppdatera de tre variablerna: 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.microsoftonline.com";
    const string wdatpResourceId = "https://api.securitycenter.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;
    

Använda Python

Se Hämta token med Python.

Använd Avokrypt

Anteckning

Följande procedur förutsätter att Avig för Windows är redan installerat på datorn.

  1. Öppna en kommandotolk och ange CLIENT_ID ditt Azure-program-ID.

  2. Ställ CLIENT_SECRET till Azure-programhemligheten.

  3. Ange TENANT_ID Azure-klientorganisations-ID för kunden som vill använda appen för att komma åt Defender för Slutpunkt.

  4. Kör följande kommando:

    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
    

    Du får ett svar i följande formulär:

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

Verifiera token

Se till att du har fått rätt token:

  1. Kopiera och klistra in den token du fick i föregående steg i JWT för att avkoda den.

  2. Verifiera att du får ett anspråk som säger "roller" med rätt behörighet.

    I följande bild kan du se en avkodad token som förvärvats från en app med behörighet till alla Microsoft Defender för Endpoints roller:

    Bild på tokenverifiering.

Använda token för att komma åt Microsoft Defender för Endpoint API

  1. Välj det API du vill använda. Mer information finns i Defender för slutpunkts-API:er som stöds.
  2. Ange ett auktoriseringshuvud i http-begäran som du skickar till "Bearer {token}" (Bearer är auktoriseringsschemat).
  3. Utgångstiden för token är en timme. Du kan skicka fler än en begäran med samma token.

Följande är ett exempel på att skicka en begäran om att få en lista med aviseringar med hjälp av 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

Se även