Opret en app med partneradgang til Microsoft Defender XDR API'er
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 Opret 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 en daemon), skal du se Opret 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:
- 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.
Da denne app er flerlejer, skal du også have administratorsamtykke fra hver lejer på vegne af brugerne.
I denne artikel forklares det, hvordan du:
- Opret 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:
- Opret 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.
Log på Azure.
Gå til Microsoft Entra ID>Appregistreringer>Ny registrering.
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.
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.
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 administrator fra din brugers lejer skal se samtykkelinket og godkende din app.
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å som administrator af brugerens lejer og give samtykke til programmet.
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.
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.
# 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
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
):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 bruger, 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://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"}
- 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
og AdvancedHunting.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 uden en bruger
- Opret en app for at få adgang til Microsoft Defender XDR API'er på vegne af en bruger
- 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.