Skapa en app med partneråtkomst till Microsoft 365 Defender-API:erCreate an app with partner access to Microsoft 365 Defender APIs

Viktigt

Det förbättrade Microsoft 365 Säkerhetscenter är nu tillgänglig.The improved Microsoft 365 security center is now available. Med den här nya upplevelsen kommer Defender för Endpoint, Defender för Office, 365 Microsoft 365 Defender och annat till Microsoft 365 säkerhetscenter.This new experience brings Defender for Endpoint, Defender for Office 365, Microsoft 365 Defender, and more into the Microsoft 365 security center. Läs om de senaste.Learn what's new.

Gäller för:Applies to:

  • Microsoft 365 DefenderMicrosoft 365 Defender

Viktigt

En del information gäller förinstallerad produkt som kan ha ändrats mycket innan den släpps kommersiellt.Some information relates to prereleased product which may be substantially modified before it's commercially released. Microsoft lämnar inga garantier, uttryckliga eller underförstådda, med avseende på den information som anges här.Microsoft makes no warranties, express or implied, with respect to the information provided here.

På den här sidan beskrivs hur du skapar en Azure Active Directory-app som har programbehörighet till Microsoft 365 Defender för användare i flera klientorganisationen.This page describes how to create an Azure Active Directory app that has programmatic access to Microsoft 365 Defender, on behalf of users across multiple tenants. Appar med flera klientorganisationer är användbara när du ska använda stora grupper av användare.Multi-tenant apps are useful for serving large groups of users.

Om du behöver programmeringsåtkomst till Microsoft 365 Defender åt en enskild användare kan du gå till Skapa en app för att få åtkomst till Microsoft 365 Defender-API:er för en användares räkning.If you need programmatic access to Microsoft 365 Defender on behalf of a single user, see Create an app to access Microsoft 365 Defender APIs on behalf of a user. Om du behöver åtkomst utan att en användare uttryckligen definierats (till exempel om du skriver en bakgrundsapp eller ett bakgrundsljud), se Skapa en app för att komma åt Microsoft 365 Defenderutan en användare.If you need access without a user explicitly defined (for example, if you're writing a background app or daemon), see Create an app to access Microsoft 365 Defender without a user. Om du är osäker på vilken typ av åtkomst du behöver kan du gå till Komma igång.If you're not sure which kind of access you need, see Get started.

Microsoft 365 Defender visar mycket av sina data och åtgärder via en uppsättning programmässiga API:er.Microsoft 365 Defender exposes much of its data and actions through a set of programmatic APIs. De här API:erna hjälper dig att automatisera arbetsflöden och utnyttja funktionerna i Microsoft 365 Defender.Those APIs help you automate workflows and make use of Microsoft 365 Defender's capabilities. Den här API-åtkomsten kräver OAuth2.0-autentisering.This API access requires OAuth2.0 authentication. Mer information finns i OAuth 2.0 Auktoriseringskodflöde.For more information, see OAuth 2.0 Authorization Code Flow.

I allmänhet måste du vidta följande steg för att använda följande API:er:In general, you'll need to take the following steps to use these APIs:

  • Skapa ett Azure Active Directory-program (Azure AD).Create an Azure Active Directory (Azure AD) application.
  • Hämta en åtkomsttoken med det här programmet.Get an access token using this application.
  • Använd tokenet för att få åtkomst till Microsoft 365 Defender API.Use the token to access 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.Since this app is multi-tenant, you'll also need admin consent from each tenant on behalf of its users.

I den här artikeln förklaras hur du:This article explains how to:

  • Skapa ett Azure AD-program med flera innehavareCreate a multi-tenant Azure AD application
  • Få ett auktoriserat medgivande från din användaradministratör för programmet om att få åtkomst till de Microsoft 365 Defender-resurser som behövs.Get authorized consent from your user administrator for your application to access the Microsoft 365 Defender that resources it needs.
  • Hämta en åtkomsttoken till Microsoft 365 DefenderGet an access token to Microsoft 365 Defender
  • Verifiera tokenValidate the token

Microsoft 365 Defender visar mycket av sina data och åtgärder via en uppsättning programmässiga API:er.Microsoft 365 Defender exposes much of its data and actions through a set of programmatic APIs. De HÄR API:erna hjälper dig att automatisera arbetsflöden och nyfikna baserat på microsoft 365 Defender-funktioner.Those APIs will help you automate work flows and innovate based on Microsoft 365 Defender capabilities. API-åtkomst kräver OAuth2.0-autentisering.The API access requires OAuth2.0 authentication. Mer information finns i OAuth 2.0 Auktoriseringskodflöde.For more information, see OAuth 2.0 Authorization Code Flow.

I allmänhet måste du vidta följande steg för att använda API:er:In general, you’ll need to take the following steps to use the APIs:

  • Skapa ett Azure AD-program med flera innehavare.Create a multi-tenant Azure AD application.
  • Få auktoriserat (godkännande) av användaradministratören för programmet för att få åtkomst till De Microsoft 365 Defender-resurser som behövs.Get authorized (consent) by your user administrator for your application to access Microsoft 365 Defender resources it needs.
  • Hämta en åtkomsttoken med det här programmet.Get an access token using this application.
  • Använd tokenet för att få åtkomst till Microsoft 365 Defender API.Use the token to access Microsoft 365 Defender API.

Följande steg hjälper dig att skapa ett Azure AD-program med flera innehavare, få en åtkomsttoken till Microsoft 365 Defender och verifiera token.The following steps with guide you how to create a multi-tenant Azure AD application, get an access token to Microsoft 365 Defender and validate the token.

Skapa appen för flera innehavareCreate the multi-tenant app

  1. Logga in i Azure som en användare med rollen Global administratör.Sign in to Azure as a user with the Global Administrator role.

  2. Gå till Azure Active Directory-appregistreringar > > Ny registrering.Navigate to Azure Active Directory > App registrations > New registration.

    Bild av Microsoft Azure och navigering till programregistrering

  3. I registreringsformuläret:In the registration form:

    • Välj ett namn på programmet.Choose a name for your application.
    • Välj Konton i valfri organisationskatalog (Azure AD-katalog) – Multitenant från Kontotyper som stöds .From Supported account types, select Accounts in any organizational directory (Any Azure AD directory) - Multitenant.
    • Fyll i avsnittet Omdirigera URI.Fill out the Redirect URI section. Välj typ webb och ge omdirigerings-URI som https://portal.azure.com .Select type Web and give the redirect URI as https://portal.azure.com.

    När du har fyllt i formuläret väljer du Registrera.After you're done filling out the form, select Register.

    Bild på formuläret Registrera ett program

  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.On your application page, select API Permissions > Add permission > APIs my organization uses >, type Microsoft Threat Protection, and select Microsoft Threat Protection. Appen kan nu komma åt Microsoft 365 Defender.Your app can now access Microsoft 365 Defender.

    Tips

    Microsoft Threat Protection är ett tidigare namn för Microsoft 365 Defender och visas inte i den ursprungliga listan.Microsoft Threat Protection is a former name for Microsoft 365 Defender, and will not appear in the original list. Du måste börja skriva namnet i textrutan för att det ska visas.You need to start writing its name in the text box to see it appear.

    Bild av val av API-behörighet

  5. Välj Programbehörigheter.Select Application permissions. Välj relevanta behörigheter för ditt scenario (till exempel Incident.Läsa.Alla) och välj sedan Lägg till behörigheter.Choose the relevant permissions for your scenario (for example, Incident.Read.All), and then select Add permissions.

    Bild av val av API-åtkomst och API

    Anteckning

    Du måste välja rätt behörighet för ditt scenario.You need to select the relevant permissions for your scenario. Läs alla incidenter är bara ett exempel.Read all incidents is just an example. Information om vilken behörighet du behöver finns i avsnittet Behörigheter i det API du vill anropa.To determine which permission you need, please look at the Permissions section in the API you want to call.

    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".For instance, to run advanced queries, select the 'Run advanced queries' permission; to isolate a device, select the 'Isolate machine' permission.

  6. Välj Bevilja administratörsmedgivande.Select Grant admin consent. 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.Every time you add a permission, you must select Grant admin consent for it to take effect.

    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.To add a secret to the application, select Certificates & secrets, add a description to the secret, then select Add.

    Tips

    När du har valt Lägg till väljer du kopiera det genererade hemliga värdet.After you select Add, select copy the generated secret value. Du kommer inte att kunna hämta det hemliga värdet när du har lämnat.You won't be able to retrieve the secret value after you leave.

    Bild av skapa programnyckel

  8. Spela in ditt program-ID och ditt klient-ID på ett säkert ställe.Record your application ID and your tenant ID somewhere safe. De visas under Översikt din programsida.They're listed under Overview on your application page.

    Bild på skapad app-ID

  9. Lägg till programmet i användarens klientorganisation.Add the application to your user's tenant.

    Eftersom programmet interagerar med Microsoft 365 Defender åt dina användare måste det godkännas för varje klientorganisation för vilken du tänker använda det.Since your application interacts with Microsoft 365 Defender on behalf of your users, it needs be approved for every tenant on which you intend to use it.

    En global administratör från användarens klientorganisation måste visa medgivandelänken och godkänna programmet.A Global Administrator from your user's tenant needs to view the consent link and approve your application.

    Medgivandelänken är i formuläret:Consent link is of the form:

    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.The digits 00000000-0000-0000-0000-000000000000 should be replaced with your Application 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.After clicking on the consent link, sign in with the Global Administrator of the user's tenant and consent the application.

    Bild av medgivande

    Du måste också be användaren om deras klientorganisations-ID.You'll also need to ask your user for their tenant ID. Klientorganisations-ID:t är ett av identifierarna som används för att hämta åtkomsttoken.The tenant ID is one of the identifiers used to acquire access tokens.

  • Klart!Done! Ett program har registrerats!You've successfully registered an application!
  • Se exempel nedan för insamling och validering av token.See examples below for token acquisition and validation.

Hämta en åtkomsttokenGet an access token

Mer information om Azure AD-token finns i självstudiekursen om Azure AD.For more information on Azure AD tokens, see the Azure AD tutorial.

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.Although the examples in this section encourage you to paste in secret values for testing purposes, you should never hardcode secrets into an application running in production. En tredje part kan använda din hemligt för att komma åt resurser.A third party could use your secret to access resources. Du kan skydda dina apphemligheter med hjälp av Azure Key Vault.You can help keep your app's secrets secure by using Azure Key Vault. Ett praktiskt exempel på hur du kan skydda din app finns i Hantera hemligheter i dina serverappar med Azure Key Vault.For a practical example of how you can protect your app, see Manage secrets in your server apps with Azure Key Vault.

Tips

I följande exempel kan du använda en användares klientorganisations-ID för att testa att skriptet fungerar.In the following examples, use a user's tenant ID to test that the script is working.

Hämta en åtkomsttoken med Hjälp av PowerShellGet an access token using 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#Get an access token using C#

Anteckning

Följande kod testades med Nuget Microsoft.IdentityModel.Clients.ActiveDirectory 3.19.8.The following code was tested with Nuget Microsoft.IdentityModel.Clients.ActiveDirectory 3.19.8.

  1. Skapa ett nytt konsolprogram.Create a new console application.

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

  3. Lägg till följande rad:Add the following line:

    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 ):Copy and paste the following code into your app (don't forget to update the three variables: 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 PythonGet an access token using 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.securitycenter.windows.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öjaGet an access token using curl

Anteckning

Avbildning är förinstallerat på Windows 10, version 1803 och senare.Curl is pre-installed on Windows 10, versions 1803 and later. För andra versioner av Windows laddar du ned och installerar verktyget direkt från den officiella avbildningswebbplatsen.For other versions of Windows, download and install the tool directly from the official curl website.

  1. Öppna en kommandotolk och ange CLIENT_ID ditt Azure-program-ID.Open a command prompt, and set CLIENT_ID to your Azure application ID.
  2. Ställ CLIENT_SECRET till Azure-programhemligheten.Set CLIENT_SECRET to your Azure application secret.
  3. Ange TENANT_ID Azure-klientorganisations-ID för den användare som vill använda appen för att få åtkomst till Microsoft 365 Defender.Set TENANT_ID to the Azure tenant ID of the user that wants to use your app to access Microsoft 365 Defender.
  4. Kör följande kommando:Run the following command:
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:A successful response will look like this:

{"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn <truncated> aWReH7P0s0tjTBX8wGWqJUdDA"}

Verifiera tokenValidate the token

  1. Kopiera och klistra in tokenet på JSON-webbplatsen för webbtokens validator, JWT, för att avkoda den.Copy and paste the token into the JSON web token validator website, JWT, to decode it.
  2. Kontrollera att rollerna som anges i den avkodade token innehåller de önskade behörigheterna.Make sure that the roles claim within the decoded token contains the desired permissions.

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:In the following image, you can see a decoded token acquired from an app, with Incidents.Read.All, Incidents.ReadWrite.All, and AdvancedHunting.Read.All permissions:

Bild på tokenverifiering

Använda token för att få åtkomst till Microsoft 365 Defender APIUse the token to access the Microsoft 365 Defender API

  1. Välj det API du vill använda (ärenden eller avancerad sökning).Choose the API you want to use (incidents, or advanced hunting). Mer information finns i Microsoft 365 Defender-API:er som stöds.For more information, see Supported Microsoft 365 Defender APIs.
  2. I http-begäran som du ska skicka anger du i autentiseringsrubriken till , Bearer som auktoriseringsschema och token som din "Bearer" <token> verifierade token. In the http request you're about to send, set the authorization header to "Bearer" <token>, Bearer being the authorization scheme, and token being your validated token.
  3. Tokenet förfaller inom en timme.The token will expire within one hour. Du kan skicka mer än en begäran under denna tid med samma token.You can send more than one request during this time with the same token.

I följande exempel visas hur du skickar en begäran om att få en lista över incidenter med hjälp av C#.The following example shows how to send a request to get a list of incidents using 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();