Partnertilgang gjennom Microsoft Defender for endepunkt API-er

Artikkel
04/26/2024

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 endepunkt for US Government-kunder.

Tips

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

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

Denne siden beskriver hvordan du oppretter et Microsoft Entra program for å få programmatisk tilgang til Microsoft Defender for endepunkt på vegne av kundene.

Microsoft Defender for endepunkt 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 endepunkt funksjoner. 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:

Opprett et program med flere leiere Microsoft Entra.
Få godkjent(samtykke) av kundeadministratoren for at programmet skal få tilgang til Defender for endepunktressurser det trenger.
Få et tilgangstoken ved hjelp av dette programmet.
Bruk tokenet til å få tilgang 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 endepunkt og validerer tokenet.

Opprett appen for flere enheter

Logg deg på Azure-leieren med en bruker som har global administratorrolle .
Gå til Microsoft Entra ID>App-registreringer>Ny registrering.
I registreringsskjemaet:
- Velg et navn for programmet.
- Støttede kontotyper – kontoer i alle organisasjonskataloger.
- Omadresserings-URI – type: Web, URI: https://portal.azure.com
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.
- Vær oppmerksom på at WindowsDefenderATP ikke vises i den opprinnelige listen. Begynn å skrive navnet i tekstboksen for å se det vises.

Be om API-tillatelser

Hvis du vil finne ut hvilken tillatelse du trenger, kan du se gjennom Tillatelser-delen i API-en du er interessert i å ringe. For eksempel:

Hvis du vil kjøre avanserte spørringer, velger du tillatelsen Kjør avanserte spørringer
Hvis du vil isolere en enhet, velger du Isolate machine-tillatelse

I eksemplet nedenfor bruker vi tillatelsen Les alle varsler :

Velg Application permissions>Alert.Read.All> select on Add permissions
Velg Gi samtykke
- Obs! Hver gang du legger til tillatelse, må du velge gi samtykke for at den nye tillatelsen skal tre i kraft.
Legg til en hemmelighet i programmet.
- Velg Sertifikater & hemmeligheter, legg til beskrivelse i hemmeligheten, og velg Legg til.
Viktig! Når du har valgt Legg til, må du passe på å kopiere den genererte hemmelige verdien. Du kan ikke hente den etter at du har forlatt den!
Skriv ned program-ID-en:
- Gå til Oversikt på programsiden, og kopier følgende informasjon:
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 endepunkt program 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 klikket på samtykkekoblingen, logger du på med den globale administratoren for kundens tenant og samtykker i programmet.

I tillegg må du be kunden om leier-ID-en og lagre den for fremtidig bruk når du anskaffer tokenet.
Ferdig! Du har registrert et program! Se eksemplene nedenfor for tokeninnhenting og validering.

Få et eksempel på tilgangstoken

Merk: 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#

Koden nedenfor ble testet med Nuget Microsoft.Identity.Client

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.

Opprett et nytt konsollprogram
Installer NuGet Microsoft.Identity.Client
Legg til nedenfor ved hjelp av
```
using Microsoft.Identity.Client;
```

Kopier/lim inn koden nedenfor i programmet (ikke glem å oppdatere de tre variablene: tenantId, appId, og 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!

Fremgangsmåten nedenfor, antatt Curl for Windows, er allerede installert på datamaskinen

Åpne et kommandovindu.
Angi CLIENT_ID til Azure-program-ID-en.
Angi CLIENT_SECRET til Azure-programhemmeligheten.
Angi TENANT_ID til Azure-leier-ID-en til kunden som ønsker å bruke programmet til å få tilgang til Microsoft Defender for endepunkt programmet.

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 på skjemaet:

{"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.

Kopier/lim inn i JWT tokenet du fikk i forrige trinn for å dekode det.
Bekreft at du får et «roller»-krav med de ønskede tillatelsene.

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

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

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

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

Angi autorisasjonshodet i HTTP-forespørselen du sender til "Bærer {token}" (Bærer er godkjenningsskjemaet). Utløpstiden for tokenet er 1 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å