Del via

Opprette en app for å få tilgang til Microsoft Defender for endepunkt uten en bruker

  • Artikkel

Gjelder for:

Viktig

Avanserte jaktfunksjoner er ikke inkludert i Defender for Business.

Vil du oppleve Microsoft Defender for endepunkt? Registrer deg for en gratis prøveperiode.

Obs!

Hvis du er us Government-kunde, kan du bruke URI-ene som er oppført i Microsoft Defender for Endpoint for US Government-kunder.

Tips

Hvis du vil ha bedre ytelse, kan du bruke serveren nærmere geografisk plassering:

  • 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

Denne siden beskriver hvordan du oppretter et program for å få programmatisk tilgang til Defender for endepunkt uten en bruker. Hvis du trenger programmatisk tilgang til Defender for endepunkt på vegne av en bruker, kan du se Få tilgang med brukerkontekst. Hvis du ikke er sikker på hvilken tilgang du trenger, kan du se Komme i gang.

Microsoft Defender for Endpoint viser mye av dataene og handlingene gjennom et sett med programmatiske API-er. Disse API-ene vil hjelpe deg med å automatisere arbeidsflyter og innovere basert på Defender for Endpoint-funksjoner. API-tilgang krever OAuth2.0-godkjenning. Hvis du vil ha mer informasjon, kan du se OAuth 2.0 Authorization Code Flow.

Generelt må du utføre følgende trinn for å bruke API-ene:

  • Opprett et Microsoft Entra-program.
  • Få et tilgangstoken ved hjelp av dette programmet.
  • Bruk tokenet til å få tilgang til Defender for endepunkt-API.

Denne artikkelen forklarer hvordan du oppretter et Microsoft Entra-program, får et tilgangstoken til Microsoft Defender for Endpoint og validerer tokenet.

Viktig

Microsoft anbefaler at du bruker roller med færrest tillatelser. Dette bidrar til å forbedre sikkerheten for organisasjonen. Global administrator er en svært privilegert rolle som bør begrenses til nødscenarioer når du ikke kan bruke en eksisterende rolle.

Opprette en app

  1. Logg deg på Azure-portalen med en bruker som har rollen global administrator.

  2. Naviger til Registreringer> av Microsoft Entra ID-appen>Ny registrering.

    Registreringsruten for programmet

  3. Velg et navn på programmet i registreringsskjemaet, og velg deretter Registrer.

  4. Hvis du vil gi appen tilgang til Defender for endepunkt og tilordne tillatelsen Les alle varsler, velger du API-tillatelser legg til tillatelses-API-er>>organisasjonen bruker>, skriver inn WindowsDefenderATP og velger deretter WindowsDefenderATP på programsiden.

    Obs!

    WindowsDefenderATP vises ikke i den opprinnelige listen. Begynn å skrive navnet i tekstboksen for å se det vises.

    API-tillatelsesruten

    Velg Programtillatelser>Alert.Read.All, og velg deretter Legg til tillatelser.

    Informasjonsruten for programtillatelser

  5. Velg riktige tillatelser. Read All Alerts er bare et eksempel. Her er noen eksempler:

    • Hvis du vil kjøre avanserte spørringer, velger du tillatelsen Run advanced queries .
    • Hvis du vil isolere en enhet, velger du tillatelsen Isolate machine .
    • Hvis du vil finne ut hvilken tillatelse du trenger, kan du se på Tillatelser-delen i API-en du er interessert i å ringe.

  6. Velg Gi samtykke.

    Obs!

    Hver gang du legger til en tillatelse, må du velge Gi samtykke for at den nye tillatelsen skal tre i kraft.

    Siden gi tillatelser

  7. Hvis du vil legge til en hemmelighet i programmet, velger du Sertifikater & hemmeligheter, legger til en beskrivelse i hemmeligheten og velger deretter Legg til.

    Obs!

    Når du har valgt Legg til, velger du kopier den genererte hemmelige verdien. Du kan ikke hente denne verdien etter at du har forlatt den.

    Alternativet Opprett program

  8. Skriv ned program-ID-en og leier-ID-en. Gå til Oversikt på programsiden, og kopier følgende.

    De opprettede app- og leier-ID-ene

  9. Bare for Microsoft Defender for endepunktpartnere. Angi at appen skal være flerleiert (tilgjengelig i alle leiere etter samtykke). Dette er nødvendig for tredjepartsapper (for eksempel hvis du oppretter en app som er ment å kjøre i flere kunders leier). Dette er ikke nødvendig hvis du oppretter en tjeneste som du bare vil kjøre i leieren (hvis du for eksempel oppretter et program for din egen bruk som bare samhandler med dine egne data). Følg disse trinnene for å angi at appen skal være flerleiert:

    1. Gå til godkjenning, og legg til https://portal.azure.com som URI for omadressering.

    2. Velg kontoene i et hvilket som helst samtykke i organisasjonskatalogprogrammet for appen med flere leiere nederst på siden, under Støttede kontotyper.

      Du trenger at programmet godkjennes i hver leier der du har tenkt å bruke den. Dette er fordi programmet samhandler Defender for Endpoint på vegne av kunden.

      Du (eller kunden din hvis du skriver en tredjepartsapp) må velge samtykkekoblingen og godkjenne appen. Samtykket bør gjøres med en bruker som har administrative rettigheter i Active Directory.

      Samtykkekoblingen dannes på følgende måte:

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

      Hvor 00000000-0000-0000-0000-000000000000 erstattes med program-ID-en.

Ferdig! Du har registrert et program! Se eksempler nedenfor for tokeninnhenting og validering.

Få et tilgangstoken

Hvis du vil ha mer informasjon om Microsoft Entra-tokener, kan du se Microsoft Entra-opplæringen.

Bruk 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

$sourceAppIdUri = 'https://api.securitycenter.microsoft.com/.default'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/v2.0/token"
$authBody = [Ordered] @{
    scope = "$sourceAppIdUri"
    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
$token

Bruk C#:

Følgende kode ble testet med NuGet Microsoft.Identity.Client 3.19.8.

Viktig

Microsoft.IdentityModel.Clients.ActiveDirectory NuGet-pakken og Azure AD Authentication Library (ADAL) er avskrevet. Ingen nye funksjoner er lagt til siden 30. juni 2020. Vi oppfordrer deg sterkt til å oppgradere, se overføringsveiledningen for mer informasjon.

  1. Opprett et nytt konsollprogram.

  2. Installer NuGet Microsoft.Identity.Client.

  3. Legg til følgende:

    using Microsoft.Identity.Client;

  4. Kopier og lim inn følgende kode i appen (ikke glem å oppdatere de tre variablene: 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 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;

Bruk Python

Se Hent token ved hjelp av Python.

Bruk krøll

Obs!

Følgende fremgangsmåte forutsetter at Curl for Windows allerede er installert på datamaskinen.

  1. Åpne en ledetekst, og angi CLIENT_ID Azure-program-ID-en.

  2. Angi CLIENT_SECRET Azure-programhemmeligheten.

  3. Angi TENANT_ID Azure-leier-ID-en til kunden som ønsker å bruke appen til å få tilgang til Defender for Endpoint.

  4. Utfør denne kommandoen:

    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 et svar som ligner på følgende kodesnutt:

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

Validere tokenet

Kontroller at du har riktig token:

  1. Kopier og lim inn tokenet du fikk i forrige trinn i JWT for å dekode det.

  2. Valider at du får et rollekrav med de ønskede tillatelsene.

    På bildet nedenfor kan du se et dekodet token hentet fra en app med tillatelser til alle rollene til Microsoft Defender for endepunktet:

    Tokendetaljer-delen

Bruke tokenet til å få tilgang til Microsoft Defender for endepunkt-API

  1. Velg API-en du vil bruke. Hvis du vil ha mer informasjon, kan du se Støttede Defender for endepunkt-API-er.

  2. Angi godkjenningshodet i http forespørselen du sender til Bearer {token} (Bærer er godkjenningsskjemaet).

  3. Utløpstiden for tokenet er én time. Du kan sende mer enn én forespørsel med samme token.

Følgende er et eksempel på hvordan du sender en forespørsel for å få en liste over varsler ved hjelp 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 også

Tips

Vil du lære mer? Engasjer deg med Microsoft Security-fellesskapet i det tekniske fellesskapet vårt: Microsoft Defender for Endpoint Tech Community.