Opprett en app med partnertilgang til Microsoft Defender XDR API-er

  • Artikkel

Gjelder for:

  • Microsoft Defender XDR

Viktig

Noe informasjon er knyttet til forhåndsutgitt produkt som kan endres vesentlig før det utgis kommersielt. Microsoft gir ingen garantier, uttrykkelige eller underforståtte, med hensyn til informasjonen som er oppgitt her.

Denne siden beskriver hvordan du oppretter en Microsoft Entra app som har programmatisk tilgang til Microsoft Defender XDR, på vegne av brukere på tvers av flere leiere. Apper med flere leiere er nyttige for å betjene store grupper med brukere.

Hvis du trenger programmatisk tilgang til Microsoft Defender XDR på vegne av én enkelt bruker, kan du se Opprett en app for å få tilgang til Microsoft Defender XDR API-er på vegne av en bruker. Hvis du trenger tilgang uten en bruker eksplisitt definert (for eksempel hvis du skriver en bakgrunnsapp eller daemon), kan du se Opprett en app for å få tilgang til Microsoft Defender XDR uten en bruker. Hvis du ikke er sikker på hvilken type tilgang du trenger, kan du se Komme i gang.

Microsoft Defender XDR viser mye av dataene og handlingene gjennom et sett med programmatiske API-er. Disse API-ene hjelper deg med å automatisere arbeidsflyter og bruke funksjonene til Microsoft Defender XDR. Denne API-tilgangen 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 disse API-ene:

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

Siden denne appen er flerleier, trenger du også administratorsamtykke fra hver leier på vegne av brukerne.

Denne artikkelen forklarer hvordan du:

  • Opprett et program for Microsoft Entra med flere leiere
  • Få godkjent samtykke fra brukeradministratoren for at programmet skal få tilgang til Microsoft Defender XDR ressursene det trenger.
  • Få et tilgangstoken til Microsoft Defender XDR
  • Validere tokenet

Microsoft Defender XDR 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å Microsoft Defender XDR 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 program med flere leiere Microsoft Entra.
  • Få godkjent (samtykke) av brukeradministratoren for at programmet skal få tilgang til Microsoft Defender XDR ressursene det trenger.
  • Få et tilgangstoken ved hjelp av dette programmet.
  • Bruk tokenet til å få tilgang Microsoft Defender XDR API.

Følgende trinn viser deg hvordan du oppretter et program med flere leiere Microsoft Entra, får et tilgangstoken for å Microsoft Defender XDR og validere tokenet.

Opprett appen med flere leiere

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

  2. Gå til Microsoft Entra ID>App-registreringer>Ny registrering.

    Registreringsdelen for et program i Microsoft Defender-portalen

  3. I registreringsskjemaet:

    • Velg et navn for programmet.
    • Velg Kontoer i en hvilken som helst organisasjonskatalog (alle Microsoft Entra katalog) frastøttede kontotyper.
    • Fyll ut omadresserings-URI-delen . Velg skriv inn Web og gi omadresserings-URI-en som https://portal.azure.com.

    Når du er ferdig med å fylle ut skjemaet, velger du Registrer.

    Registreringsinndelinger for et program i Microsoft Defender-portalen

  4. Velg API-tillatelserLegg til tillatelses-API-er>>organisasjonen bruker> på programsiden, skriv inn Microsoft Trusselbeskyttelse og velg Microsoft Trusselbeskyttelse. Appen kan nå få tilgang til Microsoft Defender XDR.

    Tips

    Microsoft Threat Protection er et tidligere navn for Microsoft Defender XDR, og vises ikke i den opprinnelige listen. Du må begynne å skrive navnet i tekstboksen for å se det.

    Bruksdelen for API-er i Microsoft Defender-portalen

  5. Velg programtillatelser. Velg de relevante tillatelsene for scenarioet (for eksempel Incident.Read.All), og velg deretter Legg til tillatelser.

    Tillatelsesruten for et program i Microsoft Defender-portalen

    Obs!

    Du må velge de relevante tillatelsene for scenarioet. Les alle hendelser er bare et eksempel. Hvis du vil finne ut hvilken tillatelse du trenger, kan du se på Tillatelser-delen i API-en du vil kalle opp.

    Hvis du for eksempel vil kjøre avanserte spørringer, velger du tillatelsen Kjør avanserte spørringer. hvis du vil isolere en enhet, velger du tillatelsen "Isolate machine".

  6. Velg Gi administratorsamtykke. Hver gang du legger til en tillatelse, må du velge Gi administratorsamtykke for at den skal tre i kraft.

    En inndeling for å gi administratorsamtykke i Microsoft Defender-portalen

  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.

    Tips

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

    Inndelingen Hemmelig tillegg i Microsoft Defender-portalen

  8. Registrer program-ID-en og leier-ID-en din et trygt sted. De er oppført under Oversikt på programsiden.

    Oversikt-ruten i Microsoft Defender-portalen

  9. Legg til programmet i brukerens leier.

    Siden programmet samhandler med Microsoft Defender XDR på vegne av brukerne, må det godkjennes for hver leier du har tenkt å bruke den på.

    En global administrator fra brukerens leier må vise 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

    Sifrene skal erstattes 00000000-0000-0000-0000-000000000000 med program-ID-en.

    Når du har klikket på samtykkekoblingen, logger du på med den globale administratoren for brukerens tenant og samtykker i programmet.

    Siden for samtykkeprogram i Microsoft Defender-portalen

    Du må også spørre brukeren om leier-ID-en deres. Leier-ID-en er en av identifikatorene som brukes til å skaffe tilgangstokener.

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

Viktig

Selv om eksemplene i denne delen oppfordrer deg til å lime inn hemmelige verdier for testformål, bør du aldri hardkode hemmeligheter i et program som kjører i produksjon. En tredjepart kan bruke hemmeligheten din til å få tilgang til ressurser. Du kan bidra til å holde appens hemmeligheter sikre ved hjelp av Azure Key Vault. Hvis du vil ha et praktisk eksempel på hvordan du kan beskytte appen, kan du se Administrere hemmeligheter i serverappene med Azure Key Vault.

Tips

I eksemplene nedenfor kan du bruke en brukers leier-ID til å teste at skriptet fungerer.

Få et tilgangstoken ved hjelp av PowerShell

# This code gets the application context token and saves it to a file named "Latest-token.txt" under the current directory.

$tenantId = '' # Paste your directory (tenant) ID here
$clientId = '' # Paste your application (client) ID here
$appSecret = '' # Paste your own app secret here to test, then store it in a safe place!

$resourceAppIdUri = 'https://api.security.microsoft.com'
$oAuthUri = "https://login.windows.net/$tenantId/oauth2/token"

$authBody = [Ordered] @{
    resource = $resourceAppIdUri
    client_id = $clientId
    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

Få et tilgangstoken ved hjelp av C#

Obs!

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 linje:

    using Microsoft.Identity.Client;

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

Få et tilgangstoken ved hjelp av Python

import json
import urllib.request
import urllib.parse

tenantId = '' # Paste your directory (tenant) ID here
clientId = '' # Paste your application (client) ID here
appSecret = '' # Paste your own app secret here to test, then store it in a safe place, such as the Azure Key Vault!

url = "https://login.windows.net/%s/oauth2/token" % (tenantId)

resourceAppIdUri = 'https://api.security.microsoft.com'

body = {
    'resource' : resourceAppIdUri,
    'client_id' : clientId,
    'client_secret' : appSecret,
    'grant_type' : 'client_credentials'
}

data = urllib.parse.urlencode(body).encode("utf-8")

req = urllib.request.Request(url, data)
response = urllib.request.urlopen(req)
jsonResponse = json.loads(response.read())
aadToken = jsonResponse["access_token"]

Få et tilgangstoken ved hjelp av krøll

Obs!

Curl er forhåndsinstallert på Windows 10, versjon 1803 og nyere. Last ned og installer verktøyet direkte fra det offisielle curl-nettstedet for andre versjoner av Windows.

  1. Åpne en ledetekst, og angi CLIENT_ID til Azure-program-ID-en.
  2. Angi CLIENT_SECRET til Azure-programhemmeligheten.
  3. Angi TENANT_ID til Azure-leier-ID-en til brukeren som ønsker å bruke appen til å få tilgang til Microsoft Defender XDR.
  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

Et vellykket svar vil se slik ut:

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

Validere tokenet

  1. Kopier og lim inn tokenet i JSON-nettstedet for webtoken validator, JWT, for å dekode det.
  2. Kontroller at rollekravet i det dekodede tokenet inneholder de ønskede tillatelsene.

I illustrasjonen nedenfor kan du se et dekodet token hentet fra en app, med Incidents.Read.All, Incidents.ReadWrite.Allog AdvancedHunting.Read.All tillatelser:

Ruten Dekodede tokener i Microsoft Defender-portalen

Bruke tokenet til å få tilgang til Microsoft Defender XDR-API-en

  1. Velg API-en du vil bruke (hendelser eller avansert jakt). Hvis du vil ha mer informasjon, kan du se Støttede Microsoft Defender XDR API-er.
  2. I http-forespørselen du er i ferd med å sende, setter du autorisasjonshodet til "Bearer" <token>, Bærer er godkjenningsskjemaet og tokenet er det validerte tokenet.
  3. Tokenet utløper innen én time. Du kan sende mer enn én forespørsel i løpet av denne tiden med samme token.

Følgende eksempel viser hvordan du sender en forespørsel om å få en liste over hendelser ved hjelp av C#.

   var httpClient = new HttpClient();
   var request = new HttpRequestMessage(HttpMethod.Get, "https://api.security.microsoft.com/api/incidents");

   request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

   var response = httpClient.SendAsync(request).GetAwaiter().GetResult();

Tips

Vil du lære mer? Kommuniser med Microsoft Sikkerhet-fellesskapet i det tekniske fellesskapet vårt: Microsoft Defender XDR Tech Community.