Skapa ett program för åtkomst Microsoft 365 Defender utan en användare

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 program för att få programåtkomst till Microsoft 365 Defender utan en definierad användare, till exempel om du skapar ett bakgrundsprogram eller en bakgrundstjänst.

Om du behöver programmeringsåtkomst till Microsoft 365 Defender åt en eller flera användare går du till Skapa ett program för att få åtkomst till Microsoft 365 Defender-API:er åt en användare och Skapa ett program med partneråtkomsttill Microsoft 365 Defender API:er. 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)-program.
  • Hämta en åtkomsttoken med det här programmet.
  • Använd tokenet för att komma Microsoft 365 Defender API.

I den här artikeln förklaras hur du:

  • Skapa ett Azure AD-program
  • Hämta en åtkomsttoken för Microsoft 365 Defender
  • Verifiera token.

Skapa en app

  1. Logga in i Azure som en användare med rollen Global administratör.

  2. Gå till Azure Active Directory > Appregistreringar > Ny registrering.

    Bild av Microsoft Azure navigering till registrering av program.

  3. Välj ett namn för programmet i formuläret och välj sedan Registrera.

  4. 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 Microsoft 365 Defender namn och visas inte i den ursprungliga listan. Du måste börja skriva namnet i textrutan för att det ska visas.

    Bild av val av API-behörighet.

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

    Bild av API-åtkomst och API-val.

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

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

    Bild av bevilja behörigheter.

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

    Bild av skapa programnyckel.

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

    Bild av skapat program-ID.

  9. Endast för Microsoft 365 Defender-partner: Följ de här anvisningarna för partneråtkomst via Microsoft 365 Defender-API:er, ange att programmet ska ha flera klientorganisationsklienter så att det blir tillgängligt i alla klientorganisationen när du har fått administratörsmedgivande. Partneråtkomst krävs för appar från tredje part – till exempel om du skapar ett program som ska köras i flera kunders klientorganisation. Det är inte obligatoriskt om du skapar en tjänst som du bara vill köra i klientorganisationen, till exempel ett program för din egen användning som bara kommer att interagera med dina egna data. Så här anger du att programmet ska ha flera innehavare:

    • Gå till Autentisering och lägg till https://portal.azure.com som Redirect URI.

    • Längst ned på sidan, under Kontotyper som stöds, väljer du Konton i ett organisationskatalogprograms medgivande för appen med flera innehavare.

    Eftersom programmet interagerar Microsoft 365 Defender åt användarna, måste det godkännas för varje klientorganisation för vilken du tänker använda det.

    Den globala Active Directory-administratören för varje klientorganisation måste välja länken för medgivande och godkänna appen.

    Medgivandelänken har följande struktur:

    https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=<00000000-0000-0000-0000-000000000000>&response_type=code&sso_reload=true
    

    Siffrorna ska 00000000-0000-0000-0000-000000000000 ersättas med ditt Program-ID.

Klart! Ett program har registrerats! Se exempel nedan för insamling och validering av token.

Hämta en åtkomsttoken

Mer information om hur Azure Active Directory token finns i självstudiekursen för 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.

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, 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

Hämta en åtkomsttoken med C#

Anteckning

Följande kod testades med Nuget Microsoft.IdentityModel.Clients.ActiveDirectory 3.19.8.

  1. Skapa ett nytt konsolprogram.

  2. Installera NuGet Microsoft.IdentityModel.Clients.ActiveDirectory.

  3. Lägg till följande rad:

    using Microsoft.IdentityModel.Clients.ActiveDirectory;
    
  4. Kopiera och klistra in följande kod i programmet (glöm inte att uppdatera de tre variablerna: tenantId clientId , , 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.

  1. Öppna en kommandotolk och ange CLIENT_ID ditt Azure-program-ID.

  2. Ställ CLIENT_SECRET till Azure-programhemligheten.

  3. Ange TENANT_ID Azure-klientorganisations-ID för kunden som vill använda appen för att få åtkomst Microsoft 365 Defender.

  4. 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://api.security.microsoft.com/.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

  1. Kopiera och klistra in tokenet på JSON-webbplatsen för webbtokens validator, JWT, för att avkoda den.

  2. 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:

    Bild på tokenverifiering.

Använda tokenet för att komma åt Microsoft 365 Defender API

  1. Välj det API du vill använda (ärenden eller avancerad sökning). Mer information finns i API:er som Microsoft 365 Defender.

  2. I http-begäran som du ska skicka anger du i autentiseringsrubriken till , Bearer som auktoriseringsschema, och token som "Bearer" <token> din verifierade token.

  3. 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();