Delen via

Partnertoegang via Microsoft Defender voor Eindpunt-API's

  • Artikel

Van toepassing op:

Belangrijk

Geavanceerde opsporingsmogelijkheden zijn niet opgenomen in Defender voor Bedrijven.

Wilt u Microsoft Defender voor Eindpunt ervaren? Meld u aan voor een gratis proefversie.

Opmerking

Als u een klant van de Amerikaanse overheid bent, gebruikt u de URI's die worden vermeld in Microsoft Defender voor Eindpunt voor klanten van de Amerikaanse overheid.

Tip

Voor betere prestaties kunt u de server dichter bij uw geografische locatie gebruiken:

  • 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

Op deze pagina wordt beschreven hoe u een Microsoft Entra-toepassing maakt om programmatische toegang te krijgen tot Microsoft Defender for Endpoint namens uw klanten.

Microsoft Defender voor Eindpunt maakt veel van de gegevens en acties beschikbaar via een set programmatische API's. Met deze API's kunt u werkstromen automatiseren en innoveren op basis van de mogelijkheden van Microsoft Defender voor Eindpunt. Voor de API-toegang is OAuth2.0-verificatie vereist. Zie OAuth 2.0-autorisatiecodestroom voor meer informatie.

Over het algemeen moet u de volgende stappen uitvoeren om de API's te gebruiken:

  1. Maak een Microsoft Entra-toepassing met meerdere tenants.

  2. Vraag geautoriseerd (toestemming) van uw klantbeheerder voor uw toepassing om toegang te krijgen tot Defender voor Eindpunt-resources die deze nodig heeft.

  3. Haal een toegangstoken op met behulp van deze toepassing.

  4. Gebruik het token om toegang te krijgen tot de Microsoft Defender for Endpoint-API.

De volgende stappen helpen u bij het maken van een Microsoft Entra-toepassing, het ophalen van een toegangstoken voor Microsoft Defender voor Eindpunt en het valideren van het token.

Belangrijk

Microsoft raadt u aan rollen te gebruiken met de minste machtigingen. Dit helpt bij het verbeteren van de beveiliging voor uw organisatie. Globale beheerder is een zeer bevoorrechte rol die moet worden beperkt tot scenario's voor noodgevallen wanneer u een bestaande rol niet kunt gebruiken.

De multitenant-app maken

  1. Meld u aan bij uw Azure-tenant met de gebruiker met de rol Globale beheerder .

  2. Navigeer naar Microsoft Entra ID>App-registraties>Nieuwe registratie.

    De navigatie naar het deelvenster Toepassingsregistratie

  3. In het registratieformulier:

    • Kies een naam voor uw toepassing.

    • Ondersteunde accounttypen: accounts in elke organisatiemap.

    • Omleidings-URI - type: Web, URI: https://portal.azure.com

      De registratiepagina van de Microsoft Azure-partnertoepassing

  4. Geef uw toepassing toegang tot Microsoft Defender voor Eindpunt en wijs deze toe met de minimale set machtigingen die nodig zijn om de integratie te voltooien.

    • Selecteer op uw toepassingspagina API-machtigingenToevoegenmachtigings-API's >>die mijn organisatie gebruikt> het type WindowsDefenderATP en selecteer op WindowsDefenderATP.

    • WindowsDefenderATP wordt niet weergegeven in de oorspronkelijke lijst. Begin met het schrijven van de naam in het tekstvak om deze weer te geven.

      De optie Een machtiging toevoegen

API-machtigingen aanvragen

Als u wilt bepalen welke machtiging u nodig hebt, raadpleegt u de sectie Machtigingen in de API die u wilt aanroepen. Bijvoorbeeld:

In het volgende voorbeeld gebruiken we de machtiging Alle waarschuwingen lezen :

  1. Kies Toepassingsmachtigingen>Waarschuwing.Read.All> selecteer machtigingen toevoegen

    De optie waarmee u een machtiging kunt toevoegen

  2. Selecteer Toestemming verlenen

    • Telkens wanneer u een machtiging toevoegt, moet u toestemming verlenen selecteren om de nieuwe machtiging van kracht te laten worden.

    De optie waarmee toestemming kan worden verleend

  3. Voeg een geheim toe aan de toepassing.

    • Selecteer Certificaten & geheimen, voeg een beschrijving toe aan het geheim en selecteer Toevoegen.

    Nadat u Toevoegen hebt geselecteerd, kopieert u de gegenereerde geheime waarde. U kunt deze na vertrek niet meer ophalen.

    De sleutel app maken

  4. Noteer uw toepassings-id:

    • Ga op de toepassingspagina naar Overzicht en kopieer de volgende informatie:

      De id van de toepassing maken

  5. Voeg de toepassing toe aan de tenant van uw klant.

    U moet uw toepassing goedkeuren in elke klanttenant waar u deze wilt gebruiken. Deze goedkeuring is nodig omdat uw toepassing namens uw klant communiceert met de Microsoft Defender voor Eindpunt-toepassing.

    Een gebruiker met globale beheerder van de tenant van uw klant moet de toestemmingskoppeling selecteren en uw toepassing goedkeuren.

    Toestemmingskoppeling heeft de volgende vorm:

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

    Waar 00000000-0000-0000-0000-000000000000 moet worden vervangen door uw toepassings-id.

    Nadat u de toestemmingskoppeling hebt geselecteerd, meldt u zich aan als de globale beheerder van de tenant van de klant en geeft u toestemming voor de toepassing.

    De knop Accepteren

    Daarnaast moet u uw klant om hun tenant-id vragen en deze opslaan voor toekomstig gebruik bij het verkrijgen van het token.

  6. Gereed! U hebt een aanvraag geregistreerd! Zie de volgende voorbeelden voor het verkrijgen en valideren van tokens.

Voorbeeld van een toegangstoken ophalen

Als u namens uw klant toegangstoken wilt ophalen, gebruikt u de tenant-id van de klant voor de volgende tokenovernames.

Zie Microsoft Entra-zelfstudie voor meer informatie over Microsoft Entra-token.

PowerShell gebruiken

# 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

C gebruiken#

Belangrijk

Het NuGet-pakket Microsoft.IdentityModel.Clients.ActiveDirectory en Azure AD Authentication Library (ADAL) zijn afgeschaft. Er zijn sinds 30 juni 2020 geen nieuwe functies toegevoegd. Zie de migratiehandleiding als u een upgrade wilt uitvoeren.

  1. Maak een nieuwe consoletoepassing.

  2. Installeer NuGet Microsoft.Identity.Client.

  3. Voeg het volgende toe met behulp van code:

     using Microsoft.Identity.Client;

    Deze code is getest met NuGet Microsoft.Identity.Client.

  4. Kopieer/plak de volgende code in uw toepassing (vergeet niet de drie variabelen bij te werken: tenantId, appIden 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;

Python gebruiken

Zie Token ophalen met Python.

Curl gebruiken

Opmerking

De volgende procedure zou Curl voor Windows al op uw computer zijn geïnstalleerd

  1. Open een opdrachtvenster.

  2. Stel in CLIENT_ID op uw Azure-toepassings-id.

  3. Stel in CLIENT_SECRET op uw Azure-toepassingsgeheim.

  4. Stel in TENANT_ID op de Azure-tenant-id van de klant die uw toepassing wil gebruiken voor toegang tot de Microsoft Defender for Endpoint-toepassing.

  5. Voer de volgende opdracht uit:

    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

    U krijgt een antwoord dat lijkt op het volgende codefragment:

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

Het token valideren

Controleer of u het juiste token hebt ontvangen.

  1. Kopieer/plak in JWT het token dat u in de vorige stap hebt opgehaald om het te decoderen.

  2. Controleer of u een rolclaim krijgt met de juiste machtigingen.

    In de volgende schermopname ziet u een gedecodeerd token dat is verkregen van een toepassing met meerdere machtigingen voor Microsoft Defender voor Eindpunt:

    De pagina voor tokenvalidatie

    De tid-claim is de tenant-id waartoe het token behoort.

Het token gebruiken voor toegang tot de Microsoft Defender for Endpoint-API

  1. Kies de API die u wilt gebruiken. Zie Ondersteunde Microsoft Defender voor Eindpunt-API's voor meer informatie.

  2. Stel de autorisatieheader in de HTTP-aanvraag in Bearer {token} waarnaar u verzendt (Bearer is het autorisatieschema). De verlooptijd van het token is één uur (u kunt meer dan één aanvraag met hetzelfde token verzenden).

    Hier volgt een voorbeeld van het verzenden van een aanvraag om een lijst met waarschuwingen op te halen met behulp van 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

Zie ook

Tip

Wil je meer weten? Neem contact op met de Microsoft Security-community in onze Tech Community: Microsoft Defender for Endpoint Tech Community.