Opprett en app for å få tilgang til Microsoft Defender XDR uten en bruker

  • 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 et program for å få programmatisk tilgang til Microsoft Defender XDR uten en definert bruker, for eksempel hvis du oppretter en daemon eller bakgrunnstjeneste.

Hvis du trenger programmatisk tilgang til Microsoft Defender XDR på vegne av én eller flere brukere, kan du se Opprett en app for å få tilgang til Microsoft Defender XDR API-er på vegne av en bruker, og Opprett en app med partnertilgang til Microsoft Defender XDR API-er. 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.

Denne artikkelen forklarer hvordan du:

  • Opprett et Microsoft Entra program
  • Få et tilgangstoken til Microsoft Defender XDR
  • Valider tokenet.

Opprett en app

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

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

    Fanen Ny registrering i Microsoft Defender-portalen

  3. Velg et navn for programmet i skjemaet, og velg deretter Registrer.

  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.

    Organisasjonens API-bruksfane 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 programmet 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.

    Ruten for tillatelsesrelatert samtykke 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.

    Opprett app-ruten 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. Bare for Microsoft Defender XDR partnere: Følg disse instruksjonene for partnertilgang gjennom Microsoft Defender XDR API-er, angi at appen skal være flere leiere, slik at den kan være tilgjengelig i alle leiere når du mottar administratorsamtykke. Partnertilgang kreves for tredjepartsapper– for eksempel hvis du oppretter en app som er ment å kjøre i flere kunders leiere. Det er ikke nødvendig hvis du oppretter en tjeneste som du bare vil kjøre i leieren, for eksempel et program for din egen bruk som bare samhandler med dine egne data. Slik angir du at appen skal være flere leiere:

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

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

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

    Den globale Active Directory-administratoren for hver leier må velge samtykkekoblingen og godkjenne appen.

    Samtykkekoblingen har følgende struktur:

    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.

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.

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, such as the Azure Key Vault!

$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

    csharp
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 kunden 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://api.security.microsoft.com/.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.