Del via

Partnertilgang via Microsoft Defender for endepunkt-API-er

  • 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 Microsoft Entra-program for å få programmatisk tilgang til Microsoft Defender for Endpoint på vegne av kundene dine.

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

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

  1. Opprett et Microsoft Entra-program med flere leiere.

  2. Få godkjent(samtykke) av kundeadministratoren for at programmet skal få tilgang til Defender for endepunktressurser det trenger.

  3. Få et tilgangstoken ved hjelp av dette programmet.

  4. Bruk tokenet til å få tilgang til Microsoft Defender for endepunkt-API.

Følgende trinn veileder deg 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.

Opprett appen for flere enheter

  1. Logg deg på Azure-leieren med en bruker som har global administratorrolle .

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

    Registreringsruten for navigering til program

  3. I registreringsskjemaet:

    • Velg et navn for programmet.

    • Støttede kontotyper – kontoer i alle organisasjonskataloger.

    • Omadresserings-URI – type: Web, URI: https://portal.azure.com

      Registreringssiden for Microsoft Azure-partnerprogrammet

  4. Gi programmet tilgang til Microsoft Defender for endepunkt og tilordne det med det minimale settet med tillatelser som kreves for å fullføre integreringen.

    • På programsiden velger du API-tillatelser>Legg til tillatelses-API-er>organisasjonen min bruker> , skriver inn WindowsDefenderATP og velger WindowsDefenderATP.

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

      Alternativet Legg til en tillatelse

Be om API-tillatelser

Hvis du vil finne ut hvilken tillatelse du trenger, kan du se gjennom Tillatelser-delen i API-en du vil kalle opp. For eksempel:

I eksemplet nedenfor bruker vi tillatelsen Les alle varsler :

  1. Velg Application permissions>Alert.Read.All> select on Add permissions

    Alternativet som gjør det mulig å legge til en tillatelse

  2. Velg Gi samtykke

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

    Alternativet som tillater at samtykke gis

  3. Legg til en hemmelighet i programmet.

    • Velg Sertifikater & hemmeligheter, legg til beskrivelse i hemmeligheten, og velg Legg til.

    Når du har valgt Legg til, må du kopiere den genererte hemmelige verdien. Du kan ikke hente den etter at du har forlatt den!

    Opprett app-nøkkelen

  4. Skriv ned program-ID-en:

    • Gå til Oversikt på programsiden, og kopier følgende informasjon:

      ID-en for oppretting av programmet

  5. Legg til programmet i kundens leier.

    Du trenger at programmet godkjennes i hver kundeleier der du har tenkt å bruke den. Denne godkjenningen er nødvendig fordi programmet samhandler med Microsoft Defender for Endpoint-programmet på vegne av kunden.

    En bruker med global administrator fra kundens leier må velge samtykkekoblingen og godkjenne programmet.

    Samtykkekoblingen er av skjemaet:

    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 skal erstattes med program-ID-en.

    Når du har valgt samtykkekoblingen, logger du på som global administrator for kundens tenant og samtykker i programmet.

    Godta-knappen

    I tillegg må du be kunden om leier-ID-en og lagre den for fremtidig bruk når du anskaffer tokenet.

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

Få et eksempel på tilgangstoken

Hvis du vil ha tilgangstoken på vegne av kunden, kan du bruke kundens leier-ID på følgende tokenoppkjøp.

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

Bruke 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

Bruk av C#

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. Hvis du vil oppgradere, kan du se overføringsveiledningen.

  1. Opprett et nytt konsollprogram.

  2. Installer NuGet Microsoft.Identity.Client.

  3. Legg til følgende ved hjelp av kode:

     using Microsoft.Identity.Client;

    Denne koden ble testet med NuGet Microsoft.Identity.Client.

  4. Kopier/lim inn følgende kode i programmet (ikke glem å oppdatere de tre variablene: tenantId, appIdog 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 av Python

Se Hent token ved hjelp av Python.

Bruke krøll

Obs!

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

  1. Åpne et kommandovindu.

  2. Angi CLIENT_ID Azure-program-ID-en.

  3. Angi CLIENT_SECRET Azure-programhemmeligheten.

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

  5. 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

Bekreft at du har mottatt et riktig token.

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

  2. Bekreft at du får et rollekrav med de nødvendige tillatelsene.

    I følgende skjermbilde kan du se et dekodet token hentet fra et program med flere tillatelser til Microsoft Defender for endepunkt:

    Tokenvalideringssiden

    Tid-kravet er leier-ID-en tokenet tilhører.

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 Microsoft Defender for endepunkt-API-er.

  2. Angi autorisasjonshodet i Http-forespørselen du sender til Bearer {token} (Bærer er autorisasjonsskjemaet). Utløpstiden for tokenet er én time (du kan sende mer enn én forespørsel med samme token).

    Her er et eksempel på hvordan du sender en forespørsel om å 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.