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

Gäller för:

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

Anteckning

Om du är myndighetskund i USA kan du använda de URI:er som visas i Microsoft Defender för Slutpunkt för kunder inom myndigheter i USA.

Tips

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

  • api-us.securitycenter.microsoft.com
  • api-eu.securitycenter.microsoft.com
  • api-uk.securitycenter.microsoft.com

På den här sidan beskrivs hur du skapar ett Azure Active Directory -program (Azure AD) för att få programmässiga åtkomst till Microsoft Defender för Endpoint åt dina kunder.

Microsoft Defender för slutpunkt visar mycket av dess data och åtgärder via en uppsättning programmässiga API:er. De här API:erna hjälper dig att automatisera arbetsflöden och nya funktioner baserat på Microsoft Defender för Slutpunkt-funktioner. 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 din kundadministratör för programmet för att få tillgång till Defender för de Endpoint-resurser som behövs.
  • Hämta en åtkomsttoken med det här programmet.
  • Använd tokenet för att få åtkomst till Microsoft Defender för Endpoint API.

Följande steg vägleder dig hur du skapar ett Azure AD-program, hämtar en åtkomsttoken till Microsoft Defender för Endpoint och verifierar token.

Skapa appen för flera innehavare

  1. Logga in på Azure-klienten med användare som har rollen global administratör.

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

    Bild av Microsoft Azure navigering till registreringen av appen.

  3. I registreringsformuläret:

    • Välj ett namn på programmet.

    • Kontotyper som stöds – konton i valfri organisationskatalog.

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

    Bild av Microsoft Azure registrera partnerprogram.

  4. Tillåt att programmet får åtkomst till Microsoft Defender för Endpoint och tilldela det med minimal mängd behörigheter som krävs för att slutföra integreringen.

    • Välj API-behörigheter Lägg till behörighetS-API:er som min organisation använder för > > > WindowsDefenderATP och välj på WindowsDefenderATP.

    • Obs! WindowsDefenderATP visas inte i den ursprungliga listan. Börja skriva namnet i textrutan så att det visas.

      lägg till behörighet.

Begära API-behörigheter

Ta reda på vilken behörighet du behöver i avsnittet Behörigheter i API:t som du vill anropa. Till exempel:

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

  1. Välj Avisering om > programbehörigheter.Read.All > på Lägg till behörigheter

    appbehörigheter.

  2. Välj Bevilja medgivande

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

    Bild av bevilja behörigheter.

  3. Gör programmet hemligt.

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

    Viktigt: Efter att du klickat på Lägg till kopierar du det genererade hemliga värdet. Du kan inte hämta igen när du har lämnat!

    Bild av skapa programnyckel.

  4. Skriv ned ditt program-ID:

    • Gå till Översikt på programsidan och kopiera följande information:

    Bild av skapat program-ID.

  5. Lägg till programmet i kundens klientorganisation.

    Du behöver att programmet ska godkännas i varje kundklientorganisation där du tänker använda det. Det beror på att ditt program interagerar med Microsoft Defender för Endpoint-programmet åt din kund.

    En användare med global administratör från kundens klientorganisation måste välja 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=true
    

    Där 00000000-0000-0000-0000-00000000000 ska ersättas med ditt Program-ID

    När du klickat på medgivandelänken loggar du in med den globala administratören för kundens klientorganisation och godkänner programmet.

    Bild av medgivande.

    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 exempel nedan för insamling och validering av token.

Exempel på åtkomsttoken

Obs! Om du vill få åtkomsttoken åt kunden använder du kundens klientorganisations-ID vid följande tokeninköp.

Mer information om token AAD finns i AAD självstudiekurs

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

Koden nedan testades med Nuget Microsoft.IdentityModel.Clients.ActiveDirectory

  • Skapa ett nytt konsolprogram

  • Installera NuGet Microsoft.IdentityModel.Clients.ActiveDirectory

  • Lägg till nedan med

    using Microsoft.IdentityModel.Clients.ActiveDirectory;
    
  • Kopiera/klistra in nedanstående kod i programmet (glöm inte att uppdatera de tre variablerna: tenantId appId , och 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 wdatpResourceId = "https://api.securitycenter.microsoft.com";
    
    AuthenticationContext auth = new AuthenticationContext($"{authority}/{tenantId}/");
    ClientCredential clientCredential = new ClientCredential(appId, appSecret);
    AuthenticationResult authenticationResult = auth.AcquireTokenAsync(wdatpResourceId, clientCredential).GetAwaiter().GetResult();
    string token = authenticationResult.AccessToken;
    

Använda Python

Se Hämta token med Python

Använda Avokrypt

Anteckning

Enligt nedanstående Avr för Windows är redan installerat på datorn

  • Öppna ett kommandofönster
  • Ange CLIENT_ID ditt Azure-program-ID
  • Ställ CLIENT_SECRET till Azure-programhemligheten
  • Ange TENANT_ID Azure-klientorganisations-ID för kunden som vill använda ditt program för att få åtkomst till Microsoft Defender för endpoint-programmet
  • 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 på formuläret:

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

Verifiera token

Sanity-kontroll för att kontrollera att du har fått ett korrekt token:

  • Kopiera/klistra in i JWT den token du får i föregående steg för att avkoda den
  • Verifiera att du får ett anspråk om "roller" med rätt behörighet
  • På skärmbilden nedan kan du se en avkodad token som förvärvats från ett program med flera behörigheter till Microsoft Defender för Slutpunkt:
  • Anspråket "tid" är det klientorganisations-ID som token tillhör.

Bild på tokenverifiering.

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

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

  • Ange rubriken Auktorisering i http-begäran som du skickar till "Bearer {token}" (Bearer är auktoriseringsschemat)

  • Förfallodatum för token är 1 timme (du kan skicka mer än en begäran med samma token)

  • Exempel på att skicka en begäran om att få en lista med 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