Del via

Create en app til at få adgang til Microsoft Defender XDR uden en bruger

  • Artikel

Gælder for:

  • Microsoft Defender XDR

Vigtigt!

Nogle oplysninger er relateret til et forhåndsudgivet produkt, som kan blive ændret væsentligt, før det udgives kommercielt. Microsoft giver ingen garantier, hverken udtrykkelige eller underforståede, med hensyn til de oplysninger, der gives her.

På denne side beskrives det, hvordan du opretter et program for at få programmatisk adgang til Microsoft Defender XDR uden en defineret bruger, f.eks. hvis du opretter en daemon- eller baggrundstjeneste.

Hvis du har brug for programmatisk adgang til Microsoft Defender XDR på vegne af en eller flere brugere, skal du se Create en app for at få adgang til Microsoft Defender XDR API'er på vegne af en bruger og Create en app med partneradgang til Microsoft Defender XDR API'er. Hvis du ikke er sikker på, hvilken type adgang du har brug for, skal du se Kom i gang.

Microsoft Defender XDR fremviser mange af sine data og handlinger via et sæt programmatiske API'er. Disse API'er hjælper dig med at automatisere arbejdsprocesser og gøre brug af Microsoft Defender XDR funktioner. Denne API-adgang kræver OAuth2.0-godkendelse. Du kan få flere oplysninger under OAuth 2.0 Authorization Code Flow.

Generelt skal du gøre følgende for at bruge disse API'er:

  • Create et Microsoft Entra program.
  • Hent et adgangstoken ved hjælp af dette program.
  • Brug tokenet til at få adgang til Microsoft Defender XDR API.

I denne artikel forklares det, hvordan du:

  • Create et Microsoft Entra program
  • Hent et adgangstoken til Microsoft Defender XDR
  • Valider tokenet.

Create en app

  1. Log på Azure som bruger med rollen Global administrator .

  2. Gå til Microsoft Entra ID>Appregistreringer>Ny registrering.

    Fanen Ny registrering på Microsoft Defender-portalen

  3. Vælg et navn til dit program i formularen, og vælg derefter Registrer.

  4. På din programside skal du vælge API-tilladelser>TilføjtilladelseS-API'er>, som min organisation bruger>, skriv Microsoft Threat Protection, og vælg Microsoft Threat Protection. Din app kan nu få adgang til Microsoft Defender XDR.

    Tip

    Microsoft Threat Protection er et tidligere navn på Microsoft Defender XDR og vises ikke på den oprindelige liste. Du skal begynde at skrive navnet i tekstfeltet for at se det blive vist.

    Brugsfanen for organisationens API'er på portalen Microsoft Defender

  5. Vælg Programtilladelser. Vælg de relevante tilladelser til dit scenarie (f.eks . Incident.Read.All), og vælg derefter Tilføj tilladelser.

    Ruden med programtilladelser på Microsoft Defender-portalen

    Bemærk!

    Du skal vælge de relevante tilladelser til dit scenarie. Læs alle hændelser er blot et eksempel. Hvis du vil finde ud af, hvilken tilladelse du har brug for, skal du se afsnittet Tilladelser i den API, du vil kalde.

    Hvis du f.eks. vil køre avancerede forespørgsler, skal du vælge tilladelsen 'Kør avancerede forespørgsler'. Hvis du vil isolere en enhed, skal du vælge tilladelsen "Isoler computer".

  6. Vælg Giv administratorsamtykke. Hver gang du tilføjer en tilladelse, skal du vælge Giv administratorsamtykke , for at den kan træde i kraft.

    Ruden med samtykketildelt i portalen Microsoft Defender

  7. Hvis du vil føje en hemmelighed til programmet, skal du vælge Certifikater & hemmeligheder, føje en beskrivelse til hemmeligheden og derefter vælge Tilføj.

    Tip

    Når du har valgt Tilføj, skal du vælge kopiér den genererede værdi for hemmelighed. Du kan ikke hente værdien for hemmeligheden, når du er gået.

    Ruden Opret app på Microsoft Defender-portalen

  8. Registrer dit program-id og dit lejer-id et sikkert sted. De vises under Oversigt på din programside.

    Ruden Oversigt på Microsoft Defender-portalen

  9. Kun for Microsoft Defender XDR partnere: Følg disse instruktioner for partneradgang via api'erne til Microsoft Defender XDR, angiv din app til at være multilejer, så den kan være tilgængelig i alle lejere, når du har modtaget administratorsamtykke. Partneradgang er påkrævet for tredjepartsapps – f.eks. hvis du opretter en app, der er beregnet til at køre i flere kunders lejere. Det er ikke påkrævet , hvis du opretter en tjeneste, som du kun vil køre i din lejer, f.eks. et program til dit eget forbrug, der kun interagerer med dine egne data. Sådan angiver du, at din app skal være multilejer:

    • Gå til Godkendelse, og tilføj https://portal.azure.com som omdirigerings-URI'en.

    • Nederst på siden under Understøttede kontotyper skal du vælge Konti i alle organisationsmappeprogrammers samtykke til din app med flere lejere.

    Da dit program interagerer med Microsoft Defender XDR på vegne af dine brugere, skal det godkendes for hver lejer, du vil bruge det på.

    Den globale Active Directory-administrator for hver lejer skal vælge samtykkelinket og godkende din app.

    Samtykkelinket 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

    Cifrene 00000000-0000-0000-0000-000000000000 skal erstattes med dit program-id.

Gjort! Du har registreret et program! Se eksempler nedenfor for at få oplysninger om tokenerhvervelse og -validering.

Hent et adgangstoken

Du kan få flere oplysninger om Microsoft Entra-tokens i selvstudiet om Microsoft Entra.

Vigtigt!

Selvom eksemplerne i dette afsnit opfordrer dig til at indsætte hemmelige værdier til testformål, bør du aldrig hardcode hemmeligheder i et program, der kører i produktion. En tredjepart kan bruge din hemmelighed til at få adgang til ressourcer. Du kan hjælpe med at beskytte din apps hemmeligheder ved hjælp af Azure Key Vault. Hvis du vil have et praktisk eksempel på, hvordan du kan beskytte din app, skal du se Administrer hemmeligheder i dine serverapps med Azure Key Vault.

Hent et adgangstoken ved hjælp af 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

Hent et adgangstoken ved hjælp af C#

Bemærk!

Følgende kode blev testet med Nuget Microsoft.Identity.Client 3.19.8.

Vigtigt!

NuGet-pakken Microsoft.IdentityModel.Clients.ActiveDirectory og ADAL (Azure AD Authentication Library) frarådes. Der er ikke tilføjet nye funktioner siden den 30. juni 2020. Vi opfordrer dig på det kraftigste til at opgradere, se migreringsvejledningen for at få flere oplysninger.

  1. Create et nyt konsolprogram.

  2. Installér NuGet Microsoft.Identity.Client.

  3. Tilføj følgende linje:

    using Microsoft.Identity.Client;

  4. Kopiér og indsæt følgende kode i din app (glem ikke at opdatere de tre variabler: 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;

Hent et adgangstoken ved hjælp af 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 adgangstoken ved hjælp af krøller

Bemærk!

Curl er forudinstalleret på Windows 10, version 1803 og nyere. For andre versioner af Windows, downloade og installere værktøjet direkte fra den officielle curl hjemmeside.

  1. Åbn en kommandoprompt, og angiv CLIENT_ID til dit Azure-program-id.

  2. Angiv CLIENT_SECRET til din Azure-programhemmelighed.

  3. Angiv TENANT_ID til Azure-lejer-id'et for den kunde, der vil bruge din app til at få adgang til Microsoft Defender XDR.

  4. Kør følgende kommando:

    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 sådan ud:

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

Valider tokenet

  1. Kopiér og indsæt tokenet på JSON-webtokenets validatorwebsted, JWT, for at afkode det.

  2. Sørg for, at rollekravet i det afkodede token indeholder de ønskede tilladelser.

    På følgende billede kan du se et afkodet token, der er hentet fra en app, med Incidents.Read.Alltilladelserne , Incidents.ReadWrite.Allog AdvancedHunting.Read.All :

    Ruden Afkodet token på Microsoft Defender-portalen

Brug tokenet til at få adgang til API'en til Microsoft Defender XDR

  1. Vælg den API, du vil bruge (hændelser eller avanceret jagt). Du kan få flere oplysninger under Understøttede Microsoft Defender XDR API'er.

  2. I den http-anmodning, du er ved at sende, skal du angive godkendelsesheaderen til "Bearer" <token>, Ihændehaver er godkendelsesskemaet, og tokenet er dit validerede token.

  3. Tokenet udløber inden for en time. Du kan sende mere end én anmodning i denne periode med det samme token.

I følgende eksempel kan du se, hvordan du sender en anmodning for at få en liste over hændelser ved hjælp af 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();

Tip

Vil du vide mere? Kontakt Microsoft Security-community'et i vores Tech Community: Microsoft Defender XDR Tech Community.