Del via

Create en app med partneradgang til Microsoft Defender XDR API'er

  • 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 en Microsoft Entra app, der har programmatisk adgang til Microsoft Defender XDR på vegne af brugere på tværs af flere lejere. Apps med flere lejere er nyttige til at betjene store grupper af brugere.

Hvis du har brug for programmatisk adgang til Microsoft Defender XDR på vegne af en enkelt bruger, skal du se Create en app for at få adgang til Microsoft Defender XDR API'er på vegne af en bruger. Hvis du har brug for adgang, uden at en bruger eksplicit er defineret (f.eks. hvis du skriver en baggrundsapp eller -daemon), skal du se Create en app for at få adgang til Microsoft Defender XDR uden en bruger. 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.

Da denne app er flerlejer, skal du også have administratorsamtykke fra hver lejer på vegne af brugerne.

I denne artikel forklares det, hvordan du:

  • Create et Microsoft Entra program med flere lejere
  • Få godkendt samtykke fra din brugeradministrator til dit program for at få adgang til de Microsoft Defender XDR, som det har brug for.
  • Hent et adgangstoken til Microsoft Defender XDR
  • Valider tokenet

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 arbejdsflows og skabe innovation baseret på Microsoft Defender XDR funktioner. API-adgangen 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 API'erne:

  • Create et Microsoft Entra program med flere lejere.
  • Få godkendt (samtykke) af din brugeradministrator, så dit program kan få adgang til Microsoft Defender XDR ressourcer, det har brug for.
  • Hent et adgangstoken ved hjælp af dette program.
  • Brug tokenet til at få adgang til Microsoft Defender XDR API.

Følgende trin med vejledning i, hvordan du opretter et Microsoft Entra program med flere lejere, henter et adgangstoken til Microsoft Defender XDR og validerer tokenet.

Create appen med flere lejere

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

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

    Et programs registreringssektion på Microsoft Defender-portalen

  3. I registreringsformularen:

    • Vælg et navn til programmet.
    • Fra Understøttede kontotyper skal du vælge Konti i en hvilken som helst organisationsmappe (Alle Microsoft Entra mappe) – Multitenant.
    • Udfyld afsnittet omdirigerings-URI . Vælg skriv Web , og giv omdirigerings-URI'en som https://portal.azure.com.

    Når du er færdig med at udfylde formularen, skal du vælge Registrer.

    Et programs registreringssektioner på Microsoft Defender-portalen

  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.

    Afsnittet Brug af API'er på Microsoft Defender-portalen

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

    Et programs tilladelsesrude 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.

    Et afsnit, hvor du kan give administratorsamtykke på Microsoft Defender-portalen

  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.

    Afsnittet Tilføjelse af hemmelighed 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. Føj programmet til din brugers lejer.

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

    En global administrator fra din brugers lejer skal se samtykkelinket og godkende dit program.

    Samtykkelinket er af formularen:

    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.

    Når du har klikket på samtykkelinket, skal du logge på med den globale administrator af brugerens lejer og acceptere programmet.

    Siden med samtykkeprogram på portalen Microsoft Defender

    Du skal også bede din bruger om deres lejer-id. Lejer-id'et er et af de identifikatorer, der bruges til at hente adgangstokens.

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

Tip

I følgende eksempler skal du bruge en brugers lejer-id til at teste, om scriptet fungerer.

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!

$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):

    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 bruger, 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://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 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.