Partnertilgang gjennom Microsoft Defender for endepunkt API-er

Artikkel
11/19/2024

Gjelder for:

Viktig

Avanserte jaktfunksjoner er ikke inkludert i Defender for bedrifter.

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:

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

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

Logg deg på Azure-leieren.
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.
- WindowsDefenderATP vises ikke 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 vil kalle opp. 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-maskintillatelsen .

I eksemplet nedenfor bruker vi tillatelsen Les alle varsler :

Velg Application permissions>Alert.Read.All> select on Add permissions
Velg Gi samtykke
- 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.
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!
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 brukerkonto med riktige tillatelser for 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 deg på kundens leier og gir deretter samtykke til 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

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.

Opprett et nytt konsollprogram.
Installer NuGet Microsoft.Identity.Client.
Legg til følgende ved hjelp av kode:
```
 using Microsoft.Identity.Client;
```
Denne koden ble testet med NuGet Microsoft.Identity.Client.

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

Åpne et kommandovindu.
Angi CLIENT_ID Azure-program-ID-en.
Angi CLIENT_SECRET Azure-programhemmeligheten.
Angi TENANT_ID 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 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.

Kopier/lim inn i JWT tokenet du fikk i forrige trinn for å dekode det.
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:

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 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? Engage med Microsoft Security-fellesskapet i teknisk fellesskap: Microsoft Defender for endepunkt teknisk fellesskap.

Del via

Partnertilgang gjennom Microsoft Defender for endepunkt API-er

Opprett appen for flere enheter

Be om API-tillatelser

Få et eksempel på tilgangstoken

Bruke PowerShell

Bruk av C#

Bruk av Python

Bruke krøll

Validere tokenet

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

Se også

Tilbakemeldinger

Flere ressurser