Een app maken voor toegang Microsoft 365 Defender-API's namens een gebruikerCreate an app to access Microsoft 365 Defender APIs on behalf of a user

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 toepassing maakt om programmatische toegang te krijgen tot Microsoft 365 Defender namens één gebruiker.This page describes how to create an application to get programmatic access to Microsoft 365 Defender on behalf of a single user.

Als u programmatische toegang nodig hebt tot Microsoft 365 Defender zonder een gedefinieerde gebruiker (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 programmatic access to Microsoft 365 Defender without a defined user (for example, if you're writing a background app or daemon), see Create an app to access Microsoft 365 Defender without a user. Zie Een app maken met partnertoegang tot Microsoft 365 Defender-API'sals u toegang wilt bieden voor meerdere tenants, bijvoorbeeld als u een grote organisatie of een groep klanten dient. Zie Aan de slag als u niet zeker weet welk type toegang u nodig hebt.If you need to provide access for multiple tenants—for example, if you're serving a large organization or a group of customers—see Create an app with partner access to Microsoft 365 Defender APIs.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.

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

  • Een Azure AD-toepassing makenCreate an Azure AD application
  • Een toegangs token voor Microsoft 365 DefenderGet an access token to Microsoft 365 Defender
  • Het token validerenValidate the token

Notitie

Wanneer u toegang Microsoft 365 Defender API namens een gebruiker, hebt u de juiste toepassingsmachtigingen en gebruikersmachtigingen nodig.When accessing Microsoft 365 Defender API on behalf of a user, you will need the correct application permissions and user permissions.

Tip

Als u de machtiging hebt om een actie uit te voeren in de portal, hebt u de machtiging om de actie uit te voeren in de API.If you have the permission to perform an action in the portal, you have the permission to perform the action in the API.

Een app makenCreate an 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. Kies in het formulier een naam voor uw toepassing en voer de volgende gegevens in voor de omleidings-URI en selecteer register.In the form, choose a name for your application and enter the following information for the redirect URI, then select Register.

    Afbeelding van toepassingsvenster maken

  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

    • Kies Gedelegeerde machtigingen.Choose Delegated permissions. Kies de relevante machtigingen voor uw scenario (bijvoorbeeld Incident.Read) en selecteer vervolgens Machtigingen toevoegen.Choose the relevant permissions for your scenario (for example Incident.Read), 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.

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

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

Een toegangs token krijgenGet an access token

Zie de Azure AD-zelfstudie voor meer Azure Active Directory over uw tokens.For more information on Azure Active Directory tokens, see the Azure AD tutorial.

Toegangs token krijgen met PowerShellGet an access token using PowerShell

if(!(Get-Package adal.ps)) { Install-Package -Name adal.ps } # Install the ADAL.PS package in case it's not already present

$tenantId = '' # Paste your directory (tenant) ID here.
$clientId = '' # Paste your application (client) ID here.
$redirectUri = '' # Paste your app's redirection URI

$authority = "https://login.windows.net/$tenantId"
$resourceUrl = 'https://api.security.microsoft.com'

$response = Get-ADALToken -Resource $resourceUrl -ClientId $cleintId -RedirectUri $redirectUri -Authority $authority -PromptBehavior:Always
$response.AccessToken | clip

$response.AccessToken

Het token validerenValidate the token

  1. Kopieer en plak het token in JWT om het te decoderen.Copy and paste the token into 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();