Partneråtkomst via Microsoft Defender för Endpoint-API:er

Gäller för:

• Microsoft Defender för Endpoint Abonnemang 1
• Microsoft Defender för Endpoint Abonnemang 2
• Microsoft Defender för företag

Viktigt

Avancerade jaktfunktioner ingår inte i Defender för företag.

Vill du uppleva Microsoft Defender för Endpoint? Registrera dig för en kostnadsfri utvärderingsversion.

Obs!

Om du är en us government-kund använder du de URI:er som anges i Microsoft Defender för Endpoint för amerikanska myndighetskunder.

Tips

För bättre prestanda kan du använda servern närmare din geoplats:

• us.api.security.microsoft.com
• eu.api.security.microsoft.com
• uk.api.security.microsoft.com
• au.api.security.microsoft.com
• swa.api.security.microsoft.com
• ina.api.security.microsoft.com

Den här sidan beskriver hur du skapar ett Microsoft Entra-program för att få programmatisk åtkomst till Microsoft Defender för Endpoint för dina kunders räkning.

Microsoft Defender för Endpoint exponerar mycket av sina data och åtgärder via en uppsättning programmatiska API:er. Dessa API:er hjälper dig att automatisera arbetsflöden och innovationer baserat på Microsoft Defender för Endpoint-funktioner. API-åtkomsten kräver OAuth2.0-autentisering. Mer information finns i OAuth 2.0 Authorization Code Flow (OAuth 2.0-auktoriseringskodflöde).

I allmänhet måste du vidta följande steg för att använda API:erna:

1. Skapa ett Microsoft Entra-program för flera innehavare.

2. Få behörighet (medgivande) av din kundadministratör för att ditt program ska få åtkomst till Defender för Endpoint-resurser som behövs.

3. Hämta en åtkomsttoken med det här programmet.

4. Använd token för att komma åt Microsoft Defender för Endpoint API.

Följande steg beskriver hur du skapar ett Microsoft Entra-program, hämtar en åtkomsttoken till Microsoft Defender för Endpoint och validerar token.

Viktigt

Microsoft rekommenderar att du använder roller med minst behörighet. Detta bidrar till att förbättra säkerheten för din organisation. Global administratör är en mycket privilegierad roll som bör begränsas till nödsituationsscenarier när du inte kan använda en befintlig roll.

Skapa appen för flera klientorganisationer

1. Logga in på din Azure-klientorganisation med en användare som har rollen Global administratör .

2. Gå till Microsoft Entra ID>Appregistreringar>Ny registrering.

   

3. I registreringsformuläret:

   • Välj ett namn för ditt program.

   • Kontotyper som stöds – konton i alla organisationskataloger.

   • Omdirigerings-URI – typ: Webb, URI: https://portal.azure.com

     

4. Ge ditt program åtkomst till Microsoft Defender för Endpoint och tilldela det den minsta uppsättning behörigheter som krävs för att slutföra integreringen.

   • På programsidan väljer du API-behörigheter>Lägg till behörighets-API>:er som min organisation använder skriver>WindowsDefenderATP och väljer på WindowsDefenderATP.

   • WindowsDefenderATP visas inte i den ursprungliga listan. Börja skriva dess namn i textrutan för att se det visas.

     

Begära API-behörigheter

Om du vill ta reda på vilken behörighet du behöver läser du avsnittet Behörigheter i det API som du vill anropa. Till exempel:

• Om du vill köra avancerade frågor väljer du behörigheten Kör avancerade frågor .
• Om du vill isolera en enhet väljer du behörigheten Isolera dator .

I följande exempel använder vi behörigheten Läs alla aviseringar :

1. Välj Programbehörigheter>Alert.Read.All> välj Lägg till behörigheter

   

2. Välj Bevilja medgivande

   • Varje gång du lägger till behörighet måste du välja Bevilja medgivande för att den nya behörigheten ska börja gälla.

   

3. Lägg till en hemlighet i programmet.

   • Välj Certifikat & hemligheter, lägg till en beskrivning i hemligheten och välj Lägg till.

   När du har valt Lägg till kopierar du det genererade hemliga värdet. Du kommer inte att kunna hämta den när du har åkt!

   

4. Skriv ned ditt program-ID:

   • På programsidan går du till Översikt och kopierar följande information:

     

5. Lägg till programmet i kundens klientorganisation.

   Du behöver ditt program för att godkännas i varje kundklientorganisation där du tänker använda det. Det här godkännandet är nödvändigt eftersom ditt program interagerar med Microsoft Defender för Endpoint-programmet för din kunds räkning.

   En användare med global administratör från kundens klientorganisation måste välja medgivandelänken och godkänna ditt program.

   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=true
   

   Var 00000000-0000-0000-0000-000000000000 bör ersättas med ditt program-ID.

   När du har valt medgivandelänken loggar du in som global administratör för kundens klientorganisation och godkänner programmet.

   

   Dessutom måste du be kunden om deras klientorganisations-ID och spara det för framtida användning när du hämtar token.

6. Klart! Du har registrerat ett program! Se följande exempel för tokenförvärv och validering.

Hämta ett exempel på åtkomsttoken

Om du vill hämta åtkomsttoken för din kunds räkning använder du kundens klientorganisations-ID vid följande tokenförvärv.

Mer information om Microsoft Entra-token finns i Självstudie om Microsoft Entra.

Använda PowerShell

# That code gets the App Context Token and save it to a file named "Latest-token.txt" under the current directory
# Paste below your Tenant ID, App ID and App Secret (App key).

$tenantId = '' ### Paste your tenant ID here
$appId = '' ### Paste your Application ID here
$appSecret = '' ### Paste your Application key here

$resourceAppIdUri = 'https://api.securitycenter.microsoft.com'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
$authBody = [Ordered] @{
    resource = "$resourceAppIdUri"
    client_id = "$appId"
    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

Använda C#

Viktigt

NuGet-paketet Microsoft.IdentityModel.Clients.ActiveDirectory och Azure AD Authentication Library (ADAL) har blivit inaktuella. Inga nya funktioner har lagts till sedan den 30 juni 2020. Information om hur du uppgraderar finns i migreringsguiden.

1. Skapa ett nytt konsolprogram.

2. Installera NuGet Microsoft.Identity.Client.

3. Lägg till följande med hjälp av kod:

    using Microsoft.Identity.Client;
   

   Den här koden testades med NuGet Microsoft.Identity.Client.

4. Kopiera/klistra in följande kod i programmet (glöm inte att uppdatera de tre variablerna: tenantId, appIdoch 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;
   

Använda Python

Se Hämta token med Python.

Använda Curl

Obs!

Följande procedur förutsätter att Curl för Windows redan är installerat på datorn

1. Öppna ett kommandofönster.

2. Ange CLIENT_ID till ditt Azure-program-ID.

3. Ange CLIENT_SECRET till din Azure-programhemlighet.

4. Ange TENANT_ID till Azure-klientorganisations-ID för kunden som vill använda ditt program för att få åtkomst till Microsoft Defender för Endpoint-programmet.

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

   Du får ett svar som liknar följande kodfragment:

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

Verifiera token

Bekräfta att du har fått rätt token.

1. Kopiera/klistra in den token som du fick i föregående steg i JWT för att avkoda den.

2. Bekräfta att du får ett rollanspråk med rätt behörigheter.

   I följande skärmbild visas en avkodad token som hämtats från ett program med flera behörigheter till Microsoft Defender för Endpoint:

   

   Anspråket "tid" är det klientorganisations-ID som token tillhör.

Använda token för att komma åt Microsoft Defender för Endpoint API

1. Välj det API som du vill använda. Mer information finns i Microsoft Defender för Endpoint-API:er som stöds.

2. Ange auktoriseringsrubriken i http-begäran som du skickar till Bearer {token} (Ägarna är auktoriseringsschemat). Förfallotiden för token är en timme (du kan skicka fler än en begäran med samma token).

   Här är ett exempel på hur du skickar en begäran om att få en lista över aviseringar med C#:

   var httpClient = new HttpClient();
   
   var request = new HttpRequestMessage(HttpMethod.Get, "https://api.securitycenter.microsoft.com/api/alerts");
   
   request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
   
   var response = httpClient.SendAsync(request).GetAwaiter().GetResult();
   
    // Do something useful with the response
   

Se även

• Microsoft Defender för Endpoint API:er som stöds
• Få åtkomst till Microsoft Defender för Endpoint för en användares räkning

Tips

Vill du veta mer? Interagera med Microsoft Security-communityn i vår Tech Community: Microsoft Defender för Endpoint Tech Community.