Een app maken met partnertoegang tot Microsoft 365 Defender-API'sCreate an app with partner access to Microsoft 365 Defender APIs

Belangrijk

Het verbeterde Microsoft 365-beveiligingscentrum is nu beschikbaar.The improved Microsoft 365 security center is now available. Deze nieuwe ervaring brengt Defender voor Eindpunt, Defender voor Office 365, Microsoft 365 Defender en meer naar het Microsoft 365-beveiligingscentrum.This new experience brings Defender for Endpoint, Defender for Office 365, Microsoft 365 Defender, and more into the Microsoft 365 security center. Ontdek wat er nieuw is.Learn what's new.

Van toepassing op:Applies to:

  • Microsoft 365 DefenderMicrosoft 365 Defender

Belangrijk

Sommige informatie is gerelateerd aan voorlopige productversies die mogelijk aanzienlijk gewijzigd worden voordat ze commercieel gepubliceerd worden.Some information relates to prereleased product which may be substantially modified before it's commercially released. Microsoft geeft geen garantie, uitdrukkelijk of impliciet, met betrekking tot de informatie die hier wordt beschreven.Microsoft makes no warranties, express or implied, with respect to the information provided here.

Op deze pagina wordt beschreven hoe u een Azure Active Directory maakt met programmatische toegang tot Microsoft 365 Defender, namens gebruikers in meerdere tenants.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. Multi-tenant-apps zijn handig voor het bedienen van grote groepen gebruikers.Multi-tenant apps are useful for serving large groups of users.

Als u programmatische toegang nodig hebt tot Microsoft 365 Defender namens één gebruiker, zie Een app maken voor toegang tot Microsoft 365 Defender-API's namens een gebruiker.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. Als u toegang nodig hebt zonder dat een gebruiker expliciet is gedefinieerd (bijvoorbeeld als u een achtergrond-app of daemon schrijft), zie Een app maken voor toegang tot Microsoft 365 Defender zonder een gebruiker.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. Zie Aan de slag als u niet zeker weet welk type toegang u nodig hebt.If you're not sure which kind of access you need, see Get started.

Microsoft 365 In Defender worden veel van de gegevens en acties via een set programmatische API's openbaar.Microsoft 365 Defender exposes much of its data and actions through a set of programmatic APIs. Met deze API's kunt u werkstromen automatiseren en gebruikmaken van Microsoft 365 de mogelijkheden van Defender.Those APIs help you automate workflows and make use of Microsoft 365 Defender's capabilities. Voor deze API-toegang is OAuth2.0-verificatie vereist.This API access requires OAuth2.0 authentication. Zie OAuth 2.0 Autorisatiecodevoor Flow.For more information, see OAuth 2.0 Authorization Code Flow.

Over het algemeen moet u de volgende stappen nemen om deze API's te gebruiken:In general, you'll need to take the following steps to use these APIs:

  • Maak een Azure Active Directory (Azure AD)-toepassing.Create an Azure Active Directory (Azure AD) application.
  • Een toegangs token krijgen met deze toepassing.Get an access token using this application.
  • Gebruik het token om toegang te krijgen Microsoft 365 Defender API.Use the token to access Microsoft 365 Defender API.

Aangezien deze app multi-tenant is, hebt u ook beheerdersmachtiging nodig van elke tenant namens de gebruikers.Since this app is multi-tenant, you'll also need admin consent from each tenant on behalf of its users.

In dit artikel wordt uitgelegd hoe u:This article explains how to:

  • Een Azure AD-toepassing met meerdere tenants makenCreate a multi-tenant Azure AD application
  • Krijg geautoriseerde toestemming van uw gebruikerbeheerder voor uw toepassing om toegang te krijgen tot de Microsoft 365 Defender die resources nodig hebben.Get authorized consent from your user administrator for your application to access the Microsoft 365 Defender that resources it needs.
  • Een toegangs token voor Microsoft 365 DefenderGet an access token to Microsoft 365 Defender
  • Het token validerenValidate the token

Microsoft 365 In Defender worden veel van de gegevens en acties via een set programmatische API's openbaar.Microsoft 365 Defender exposes much of its data and actions through a set of programmatic APIs. Met deze API's kunt u werkstromen automatiseren en innoveren op basis van Microsoft 365 Defender-mogelijkheden.Those APIs will help you automate work flows and innovate based on Microsoft 365 Defender capabilities. Voor de API-toegang is OAuth2.0-verificatie vereist.The API access requires OAuth2.0 authentication. Zie OAuth 2.0 Autorisatiecodevoor Flow.For more information, see OAuth 2.0 Authorization Code Flow.

Over het algemeen moet u de volgende stappen nemen om de API's te gebruiken:In general, you’ll need to take the following steps to use the APIs:

  • Maak een Azure AD-toepassing met meerdere tenants.Create a multi-tenant Azure AD application.
  • Ontvang geautoriseerde (toestemming) van uw gebruikerbeheerder voor uw toepassing om toegang te krijgen tot Microsoft 365 Defender-bronnen die deze nodig heeft.Get authorized (consent) by your user administrator for your application to access Microsoft 365 Defender resources it needs.
  • Een toegangs token krijgen met deze toepassing.Get an access token using this application.
  • Gebruik het token om toegang te krijgen Microsoft 365 Defender API.Use the token to access Microsoft 365 Defender API.

In de volgende stappen vindt u informatie over het maken van een Azure AD-toepassing met meerdere tenants, het openen van een token voor Microsoft 365 Defender en het token valideren.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.

De multi-tenant-app makenCreate the multi-tenant app

  1. Meld u aan bij Azure als gebruiker met de rol Globale beheerder.Sign in to Azure as a user with the Global Administrator role.

  2. Navigeer naar Azure Active Directory > app-registraties Nieuwe > registratie.Navigate to Azure Active Directory > App registrations > New registration.

    Afbeelding van Microsoft Azure en navigatie naar toepassingsregistratie

  3. In het registratieformulier:In the registration form:

    • Kies een naam voor uw toepassing.Choose a name for your application.
    • Selecteer accounts in een organisatiemap (een Azure AD-adreslijst) - Multitenant in ondersteunde accounttypen.From Supported account types, select Accounts in any organizational directory (Any Azure AD directory) - Multitenant.
    • Vul de sectie Redirect URI in.Fill out the Redirect URI section. Selecteer Type Web en geef de omleidings-URI als https://portal.azure.com .Select type Web and give the redirect URI as https://portal.azure.com.

    Nadat u klaar bent met het invullen van het formulier, selecteert u Registreren.After you're done filling out the form, select Register.

    Afbeelding van het toepassingsformulier Registreren

  4. Selecteer op uw toepassingspagina API-machtigingen Machtigingen toevoegen Api's die mijn organisatie gebruikt, > gebruiken, typ Microsoft Threat Protection > > en selecteer 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. Uw app heeft nu toegang tot Microsoft 365 Defender.Your app can now access Microsoft 365 Defender.

    Tip

    Microsoft Threat Protection is een voormalige naam voor Microsoft 365 Defender en wordt niet weergegeven in de oorspronkelijke lijst.Microsoft Threat Protection is a former name for Microsoft 365 Defender, and will not appear in the original list. U moet beginnen met het schrijven van de naam in het tekstvak om deze weer te geven.You need to start writing its name in the text box to see it appear.

    Afbeelding van API-machtigingsselectie

  5. Selecteer Toepassingsmachtigingen.Select Application permissions. Kies de relevante machtigingen voor uw scenario (bijvoorbeeld Incident.Read.All) en selecteer vervolgens Machtigingen toevoegen.Choose the relevant permissions for your scenario (for example, Incident.Read.All), and then select Add permissions.

    Afbeelding van API-toegang en API-selectie

    Notitie

    U moet de relevante machtigingen voor uw scenario selecteren.You need to select the relevant permissions for your scenario. Alle incidenten lezen is slechts een voorbeeld.Read all incidents is just an example. Als u wilt bepalen welke machtiging u nodig hebt, kijkt u naar de sectie Machtigingen in de API die u wilt bellen.To determine which permission you need, please look at the Permissions section in the API you want to call.

    Als u bijvoorbeeld geavanceerde query's wilt uitvoeren,selecteert u de machtiging Geavanceerde query's uitvoeren. als u een apparaat wilt isoleren,selecteert u de machtiging 'Machine isoleren'.For instance, to run advanced queries, select the 'Run advanced queries' permission; to isolate a device, select the 'Isolate machine' permission.

  6. Selecteer Beheerdersmachtiging verlenen.Select Grant admin consent. Telkens wanneer u een machtiging toevoegt, moet u Toestemming van beheerder verlenen selecteren om deze van kracht te laten worden.Every time you add a permission, you must select Grant admin consent for it to take effect.

    Afbeelding van machtigingen verlenen

  7. Als u een geheim aan de toepassing wilt toevoegen, selecteert u Certificaten & geheimen, voegt u een beschrijving toe aan het geheim en selecteert u Vervolgens Toevoegen.To add a secret to the application, select Certificates & secrets, add a description to the secret, then select Add.

    Tip

    Nadat u Toevoegen hebt geselecteerd, selecteert u de gegenereerde geheime waarde kopiëren.After you select Add, select copy the generated secret value. U kunt de geheime waarde niet meer ophalen nadat u bent weggehaald.You won't be able to retrieve the secret value after you leave.

    Afbeelding van app-sleutel maken

  8. Neem uw toepassings-id en uw tenant-id op een veilige plaats op.Record your application ID and your tenant ID somewhere safe. Ze worden weergegeven onder Overzicht op uw toepassingspagina.They're listed under Overview on your application page.

    Afbeelding van gemaakte app-id

  9. Voeg de toepassing toe aan de tenant van uw gebruiker.Add the application to your user's tenant.

    Aangezien uw toepassing samenwerkt met Microsoft 365 Defender namens uw gebruikers, moet deze worden goedgekeurd voor elke tenant waarvoor u deze wilt gebruiken.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.

    Een globale beheerder van de tenant van uw gebruiker moet de toestemmingskoppeling bekijken en uw toepassing goedkeuren.A Global Administrator from your user's tenant needs to view the consent link and approve your application.

    De koppeling Toestemming is van het formulier: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
    

    De cijfers moeten 00000000-0000-0000-0000-000000000000 worden vervangen door uw toepassings-id.The digits 00000000-0000-0000-0000-000000000000 should be replaced with your Application ID.

    Nadat u op de toestemmingskoppeling hebt geklikt, meldt u zich aan bij de globale beheerder van de tenant van de gebruiker en stemt u in met de toepassing.After clicking on the consent link, sign in with the Global Administrator of the user's tenant and consent the application.

    Afbeelding van toestemming

    U moet ook uw gebruiker om zijn of haar tenant-id vragen.You'll also need to ask your user for their tenant ID. De tenant-id is een van de id's die worden gebruikt om toegangstokens te verkrijgen.The tenant ID is one of the identifiers used to acquire access tokens.

  • Klaar!Done! U hebt een toepassing geregistreerd.You've successfully registered an application!
  • Zie hieronder voorbeelden voor het verkrijgen en valideren van tokens.See examples below for token acquisition and validation.

Een toegangs token krijgenGet an access token

Zie de zelfstudie Azure ADvoor meer informatie over Azure AD-tokens.For more information on Azure AD tokens, see the Azure AD tutorial.

Belangrijk

Hoewel de voorbeelden in deze sectie u aanmoedigen om geheime waarden te plakken voor testdoeleinden, moet u nooit geheimen hardcoderen in een toepassing die in productie wordt uitgevoerd.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. Een derde partij kan uw geheim gebruiken om toegang te krijgen tot bronnen.A third party could use your secret to access resources. U kunt de geheimen van uw app beveiligen met Behulp van Azure Key Vault.You can help keep your app's secrets secure by using Azure Key Vault. Zie Geheimen beheren in uw server-apps met Azure Key Vault voor een praktisch voorbeeld van hoe u uw app kunt beveiligen.For a practical example of how you can protect your app, see Manage secrets in your server apps with Azure Key Vault.

Tip

Gebruik in de volgende voorbeelden de tenant-id van een gebruiker om te testen of het script werkt.In the following examples, use a user's tenant ID to test that the script is working.

Toegangs token krijgen met 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

Toegangs token krijgen met C#Get an access token using C#

Notitie

De volgende code is getest met Nuget Microsoft.IdentityModel.Clients.ActiveDirectory 3.19.8.The following code was tested with Nuget Microsoft.IdentityModel.Clients.ActiveDirectory 3.19.8.

  1. Een nieuwe consoletoepassing maken.Create a new console application.

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

  3. Voeg de volgende regel toe:Add the following line:

    using Microsoft.IdentityModel.Clients.ActiveDirectory;
    
  4. Kopieer en plak de volgende code in uw app (vergeet niet om de drie variabelen bij te werken: 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;
    

Toegangs token krijgen met 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"]

Een toegangs token krijgen met behulp van krulGet an access token using curl

Notitie

Curl is vooraf geïnstalleerd op Windows 10 versie 1803 en hoger.Curl is pre-installed on Windows 10, versions 1803 and later. Voor andere versies van Windows kunt u het hulpprogramma rechtstreeks downloaden en installeren vanaf de officiële krullenwebsite.For other versions of Windows, download and install the tool directly from the official curl website.

  1. Open een opdrachtprompt en stel CLIENT_ID in op uw Azure-toepassings-id.Open a command prompt, and set CLIENT_ID to your Azure application ID.
  2. Stel CLIENT_SECRET in op uw Azure-toepassingsgeheim.Set CLIENT_SECRET to your Azure application secret.
  3. Stel TENANT_ID azure tenant-id in van de gebruiker die uw app wil gebruiken om toegang te krijgen tot 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. Voer de volgende opdracht uit: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

Een succesvol antwoord ziet er als volgende uit:A successful response will look like this:

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

Het token validerenValidate the token

  1. Kopieer en plak het token in de JSON web token validator-website, JWT, om het te decoderen.Copy and paste the token into the JSON web token validator website, JWT, to decode it.
  2. Zorg ervoor dat de claim rollen in het gedecodeerde token de gewenste machtigingen bevat.Make sure that the roles claim within the decoded token contains the desired permissions.

In de volgende afbeelding ziet u een gedecodeerd token dat is verkregen van een app, met Incidents.Read.All Incidents.ReadWrite.All , en AdvancedHunting.Read.All machtigingen: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:

Afbeelding van tokenvalidatie

Het token gebruiken om toegang te krijgen tot Microsoft 365 Defender APIUse the token to access the Microsoft 365 Defender API

  1. Kies de API die u wilt gebruiken (incidenten of geavanceerd zoeken).Choose the API you want to use (incidents, or advanced hunting). Zie Ondersteunde api's Microsoft 365 Defender voor meer informatie.For more information, see Supported Microsoft 365 Defender APIs.
  2. Stel in de http-aanvraag die u gaat verzenden de autorisatiekop in op , Bearer is het autorisatieschema en het "Bearer" <token> token dat uw gevalideerde token is.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. Het token verloopt binnen een uur.The token will expire within one hour. U kunt in deze periode meerdere aanvragen met hetzelfde token verzenden.You can send more than one request during this time with the same token.

In het volgende voorbeeld ziet u hoe u een aanvraag verzendt om een lijst met incidenten te krijgen met 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();