Opret en app for at få adgang til Microsoft Defender XDR uden en bruger
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 Opret en app for at få adgang til Microsoft Defender XDR API'er på vegne af en bruger og Opret 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:
- Opret 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:
- Opret et Microsoft Entra program
- Hent et adgangstoken til Microsoft Defender XDR
- Valider tokenet.
Log på Azure.
Gå til Microsoft Entra ID>Appregistreringer>Ny registrering.
Vælg et navn til dit program i formularen, og vælg derefter Registrer.
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.
Vælg Programtilladelser. Vælg de relevante tilladelser til dit scenarie (f.eks . Incident.Read.All), og vælg derefter Tilføj tilladelser.
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".
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.
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.
Registrer dit program-id og dit lejer-id et sikkert sted. De vises under Oversigt på din programside.
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å.
Active Directory-administratoren 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.
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.
# 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
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.
Opret et nyt konsolprogram.
Installér NuGet Microsoft.Identity.Client.
Tilføj følgende linje:
using Microsoft.Identity.Client;
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;
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"]
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.
Åbn en kommandoprompt, og angiv CLIENT_ID til dit Azure-program-id.
Angiv CLIENT_SECRET til din Azure-programhemmelighed.
Angiv TENANT_ID til Azure-lejer-id'et for den kunde, der vil bruge din app til at få adgang til Microsoft Defender XDR.
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"}
Kopiér og indsæt tokenet på JSON-webtokenets validatorwebsted, JWT, for at afkode det.
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.All
tilladelserne ,Incidents.ReadWrite.All
ogAdvancedHunting.Read.All
:
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.
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.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();
- Oversigt over API'er Microsoft Defender XDR
- Få adgang til de Microsoft Defender XDR API'er
- Opret et program af Hello verden
- Opret en app for at få adgang til Microsoft Defender XDR API'er på vegne af en bruger
- Opret en app med partneradgang med flere lejere til Microsoft Defender XDR API'er
- Få mere at vide om API-grænser og -licenser
- Forstå fejlkoder
- Administrer hemmeligheder i dine serverapps med Azure Key Vault
- OAuth 2.0-godkendelse til brugerlogon og API-adgang
Tip
Vil du vide mere? Kontakt Microsoft Security-community'et i vores Tech Community: Microsoft Defender XDR Tech Community.