Skapa ett program med partneråtkomst till Microsoft 365 Defender API:er
Viktigt
Den förbättrade Microsoft 365 Defender-portalen är nu tillgänglig. Med den här nya upplevelsen kommer Defender för Endpoint, Defender för Office 365, 365 Microsoft 365 Defender och annat till Microsoft Defender for Cloud Apps. Läs om de senaste.
Gäller för:
- Microsoft 365 Defender
Viktigt
En del information gäller förinstallerad produkt som kan ha ändrats mycket innan den släpps kommersiellt. Microsoft lämnar inga garantier, uttryckliga eller underförstådda, med avseende på den information som anges här.
På den här sidan beskrivs hur du skapar ett Azure Active Directory-program som har programmeringsåtkomst till Microsoft 365 Defender, åt användare över flera klientorganisationar. Appar med flera klientorganisationer är användbara när du ska använda stora grupper av användare.
Om du behöver programmeringsåtkomst till Microsoft 365 Defender åt en enskild användare kan du gå till Skapa ett program för att få åtkomst Microsoft 365 Defender API:er för en användares räkning. Om du behöver åtkomst utan att en användare uttryckligen definierats (till exempel om du skriver en bakgrundsapp eller bakgrundsapp) kan du gå till Skapa ett program för att komma åt Microsoft 365 Defender utan en användare. Om du är osäker på vilken typ av åtkomst du behöver kan du gå till Komma igång.
Microsoft 365 Defender mycket av informationen och åtgärderna via ett antal programmässiga API:er. De här API:erna hjälper dig att automatisera arbetsflöden och Microsoft 365 Defender av funktionerna. Den här API-åtkomsten kräver OAuth2.0-autentisering. Mer information finns i OAuth 2.0 auktoriseringskod för Flow.
I allmänhet måste du vidta följande steg för att använda följande API:er:
- Skapa ett Azure Active Directory (Azure AD).
- Hämta en åtkomsttoken med det här programmet.
- Använd tokenet för att komma Microsoft 365 Defender API.
Eftersom appen har flera klientorganisationsbehörigheter måste du också ha administratörsmedgivande från varje klientorganisation för dess användares räkning.
I den här artikeln förklaras hur du:
- Skapa ett Azure AD-program med flera innehavare
- Få auktoriserat tillstånd från användaradministratören för programmet för att få åtkomst Microsoft 365 Defender att resurser behövs.
- Hämta en åtkomsttoken till Microsoft 365 Defender
- Verifiera token
Microsoft 365 Defender mycket av informationen och åtgärderna via ett antal programmässiga API:er. De här API:erna hjälper dig automatisera arbetsflöden och nyfikna Microsoft 365 Defender arbetsflöden. API-åtkomst kräver OAuth2.0-autentisering. Mer information finns i OAuth 2.0 auktoriseringskod för Flow.
I allmänhet måste du vidta följande steg för att använda API:er:
- Skapa ett Azure AD-program med flera innehavare.
- Få auktoriserat (medgivande) av användaradministratören för programmet för att få åtkomst Microsoft 365 Defender resurser som behövs.
- Hämta en åtkomsttoken med det här programmet.
- Använd tokenet för att komma Microsoft 365 Defender API.
Följande steg hjälper dig att skapa ett Azure AD-program med flera innehavare, få en åtkomsttoken för att Microsoft 365 Defender och verifiera token.
Skapa appen för flera innehavare
Logga in i Azure som en användare med rollen Global administratör.
Gå till Azure Active Directory > Appregistreringar > Ny registrering.

I registreringsformuläret:
- Välj ett namn på programmet.
- Välj Konton i valfri organisationskatalog (Valfri Azure AD-katalog) – Multitenant från Kontotyper som stöds .
- Fyll i avsnittet Omdirigera URI. Välj typ Webb och ange omdirigerings-URI som https://portal.azure.com .
När du har fyllt i formuläret väljer du Registrera.

På programsidan väljer du API-behörigheter Lägg till > > behörighetS-API:er som min organisation använder >, skriver Microsoft Threat Protection och väljer Microsoft Threat Protection. Nu kan du komma åt Microsoft 365 Defender.
Tips
Microsoft Threat Protection är ett tidigare namn för Microsoft 365 Defender och visas inte i den ursprungliga listan. Du måste börja skriva namnet i textrutan för att det ska visas.

Välj Programbehörigheter. Välj relevanta behörigheter för ditt scenario (till exempel Incident.Läsa.Alla) och välj sedan Lägg till behörigheter.

Anteckning
Du måste välja rätt behörighet för ditt scenario. Läs alla incidenter är bara ett exempel. Information om vilken behörighet du behöver finns i avsnittet Behörigheter i det API du vill anropa.
Om du till exempel vill köra avancerade frågorväljer du behörigheten Kör avancerade frågor. om du vill isolera enenhet väljer du behörigheten "Isolera dator".
Välj Bevilja administratörsmedgivande. Varje gång du lägger till en behörighet måste du välja Ge administratörsmedgivande för att den ska gälla.

Om du vill lägga till en hemligt i programmet väljer du Certifikat &, lägger till en beskrivning till hemligheten och väljer sedan Lägg till.
Tips
När du har valt Lägg till väljer du kopiera det genererade hemliga värdet. Du kommer inte att kunna hämta det hemliga värdet när du har lämnat.

Spela in ditt program-ID och ditt klient-ID på ett säkert ställe. De visas under Översikt på din programsida.

Lägg till programmet i användarens klientorganisation.
Eftersom programmet interagerar Microsoft 365 Defender åt användarna, måste det godkännas för varje klientorganisation som du tänker använda det för.
En global administratör från användarens klientorganisation måste visa medgivandelänken och godkänna programmet.
Medgivandelänken är i formuläret:
https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=trueSiffrorna ska
00000000-0000-0000-0000-000000000000ersättas med ditt Program-ID.När du klickat på medgivandelänken loggar du in med den globala administratören för användarens klientorganisation och godkänner programmet.

Du måste också be användaren om deras klientorganisations-ID. Klientorganisations-ID:t är ett av identifierarna som används för att hämta åtkomsttoken.
- Klart! Ett program har registrerats!
- Se exempel nedan för insamling och validering av token.
Hämta en åtkomsttoken
Mer information om Azure AD-token finns i självstudiekursen om Azure AD.
Viktigt
Även om exemplen i det här avsnittet uppmuntrar dig att klistra in i hemliga värden i testsyfte bör du aldrig hårdkoda hemligheter i ett program som körs i produktion. En tredje part kan använda din hemligt för att komma åt resurser. Du kan skydda dina apphemligheter med hjälp av Azure Key Vault. Ett praktiskt exempel på hur du kan skydda din app finns i Hantera hemligheter i dina serverappar med Azure Key Vault.
Tips
I följande exempel kan du använda en användares klientorganisations-ID för att testa att skriptet fungerar.
Hämta en åtkomsttoken med Hjälp 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!
$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
Hämta en åtkomsttoken med C#
Anteckning
Följande kod testades med Nuget Microsoft.IdentityModel.Clients.ActiveDirectory 3.19.8.
Skapa ett nytt konsolprogram.
Installera NuGet Microsoft.IdentityModel.Clients.ActiveDirectory.
Lägg till följande rad:
using Microsoft.IdentityModel.Clients.ActiveDirectory;Kopiera och klistra in följande kod i programmet (glöm inte att uppdatera de tre variablerna:
tenantIdclientId, ,appSecret):string tenantId = ""; // Paste your directory (tenant) ID here string clientId = ""; // Paste your application (client) ID here string appSecret = ""; // Paste your own app secret here to test, then store it in a safe place, such as the Azure Key Vault! const string authority = "https://login.windows.net"; const string wdatpResourceId = "https://api.security.microsoft.com"; AuthenticationContext auth = new AuthenticationContext($"{authority}/{tenantId}/"); ClientCredential clientCredential = new ClientCredential(clientId, appSecret); AuthenticationResult authenticationResult = auth.AcquireTokenAsync(wdatpResourceId, clientCredential).GetAwaiter().GetResult(); string token = authenticationResult.AccessToken;
Hämta en åtkomsttoken med 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å en åtkomsttoken genom att avböja
Anteckning
Avrullning är förinstallerat på Windows 10, version 1803 och senare. För andra versioner av Windows laddar du ned och installerar verktyget direkt från den officiella av/på-webbplatsen.
- Öppna en kommandotolk och ange CLIENT_ID ditt Azure-program-ID.
- Ställ CLIENT_SECRET till Azure-programhemligheten.
- Ange TENANT_ID azure-klientorganisations-ID för den användare som vill använda appen för att komma åt Microsoft 365 Defender.
- Kör följande 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
Ett lyckat svar ser ut så här:
{"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn <truncated> aWReH7P0s0tjTBX8wGWqJUdDA"}
Verifiera token
- Kopiera och klistra in tokenet på JSON-webbplatsen för webbtokens validator, JWT, för att avkoda den.
- Kontrollera att rollerna som anges i den avkodade token innehåller de önskade behörigheterna.
På följande bild kan du se en avkodad token som köpts från en app, med Incidents.Read.All Incidents.ReadWrite.All , och AdvancedHunting.Read.All behörigheter:

Använda tokenet för att komma åt Microsoft 365 Defender API
- Välj det API du vill använda (ärenden eller avancerad sökning). Mer information finns i API:er som Microsoft 365 Defender.
- I http-begäran som du håller på att skicka anger du auktoriseringsrubriken till , Bearer som auktoriseringsschema och token som din
"Bearer" <token>verifierade token. - Tokenet förfaller inom en timme. Du kan skicka mer än en begäran under denna tid med samma token.
I följande exempel visas hur du skickar en begäran om att få en lista över incidenter med hjälp 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();
Relaterade artiklar
- Microsoft 365 Defender API:er – översikt
- Komma åt Microsoft 365 Defender API:er
- Skapa programmet Hello world
- Skapa ett program för åtkomst Microsoft 365 Defender utan en användare
- Skapa ett program för åtkomst Microsoft 365 Defender API:er för en användares räkning
- Läs mer om API-begränsningar och licensiering
- Förstå felkoder
- Hantera hemligheter i dina serverappar med Azure-tangentvalvet
- OAuth 2.0-auktorisering för användar logga in och API-åtkomst