Skip to content

Latest commit

 

History

History
162 lines (109 loc) · 8.9 KB

api-create-app-user-context.md

File metadata and controls

162 lines (109 loc) · 8.9 KB
Raw
title description ms.service f1.keywords ms.author author ms.localizationpriority manager audience ms.collection ms.topic search.appverid ms.custom ms.date
Create an app to access Microsoft Defender XDR APIs on behalf of a user
Learn how to access Microsoft Defender XDR APIs on behalf of a user.
defender-xdr
NOCSH
macapara
mjcaparas
medium
dansimp
ITPro
m365-security
tier3
must-keep
reference
MOE150
MET150
api
08/29/2024

Create an app to access Microsoft Defender XDR APIs on behalf of a user

[!INCLUDE Microsoft Defender XDR rebranding]

Applies to:

  • Microsoft Defender XDR

Important

Some information relates to prereleased product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

This page describes how to create an application to get programmatic access to Microsoft Defender XDR on behalf of a single user.

If you need programmatic access to Microsoft Defender XDR without a defined user (for example, if you're writing a background app or daemon), see Create an app to access Microsoft Defender XDR without a user. 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 Defender XDR APIs.If you're not sure which kind of access you need, see Get started.

Microsoft Defender XDR exposes much of its data and actions through a set of programmatic APIs. Those APIs help you automate workflows and make use of Microsoft Defender XDR's capabilities. This API access requires OAuth2.0 authentication. For more information, see OAuth 2.0 Authorization Code Flow.

In general, you'll need to take the following steps to use these APIs:

  • Create a Microsoft Entra application.
  • Get an access token using this application.
  • Use the token to access Microsoft Defender XDR API.

This article explains how to:

  • Create a Microsoft Entra application
  • Get an access token to Microsoft Defender XDR
  • Validate the token

Note

When accessing Microsoft Defender XDR API on behalf of a user, you will need the correct application permissions and user permissions.

Tip

If you have the permission to perform an action in the portal, you have the permission to perform the action in the API. For more information about roles and permissions, see Manage access to Microsoft Defender XDR with Microsoft Entra global roles.

Create an app

  1. Sign in to Azure.

  2. Navigate to Microsoft Entra ID > App registrations > New registration.

    :::image type="content" source="/defender/media/atp-azure-new-app2.png" alt-text="The New registration option in the Manage pane in the Azure portal" lightbox="/defender/media/atp-azure-new-app2.png":::

  3. In the form, choose a name for your application and enter the following information for the redirect URI, then select Register.

    :::image type="content" source="/defender/media/nativeapp-create2.PNG" alt-text="The application registration pane in the Azure portal" lightbox="/defender/media/nativeapp-create2.PNG":::

  4. On your application page, select API Permissions > Add permission > APIs my organization uses >, type Microsoft Threat Protection, and select Microsoft Threat Protection. Your app can now access Microsoft Defender XDR.

    [!TIP] Microsoft Threat Protection is a former name for Microsoft Defender XDR, and will not appear in the original list. You need to start writing its name in the text box to see it appear.

    :::image type="content" source="/defender/media/apis-in-my-org-tab.PNG" alt-text="Your organization's APIs pane in the Microsoft Defender portal" lightbox="/defender/media/apis-in-my-org-tab.PNG":::

    • Choose Delegated permissions. Choose the relevant permissions for your scenario (for example Incident.Read), and then select Add permissions.

      :::image type="content" source="/defender/media/request-api-permissions-delegated.PNG" alt-text="The Delegated permissions pane in the Microsoft Defender portal" lightbox="/defender/media/request-api-permissions-delegated.PNG":::

    [!NOTE] You need to select the relevant permissions for your scenario. Read all incidents is just an example. To determine which permission you need, please look at the Permissions section in the API you want to call.

    For instance, to run advanced queries, select the 'Run advanced queries' permission; to isolate a device, select the 'Isolate machine' permission.

  5. Select Grant admin consent. Every time you add a permission, you must select Grant admin consent for it to take effect.

    :::image type="content" source="/defender/media/grant-consent-delegated.PNG" alt-text="The admin consent-granting pane in the Microsoft Defender portal" lightbox="/defender/media/grant-consent-delegated.PNG":::

  6. Record your application ID and your tenant ID somewhere safe. They're listed under Overview on your application page.

    :::image type="content" source="/defender/media/app-and-tenant-ids.png" alt-text="The Overview pane in the Microsoft Defender portal" lightbox="/defender/media/app-and-tenant-ids.png":::

Get an access token

For more information on Microsoft Entra tokens, see the Microsoft Entra tutorial.

Get an access token on behalf of a user using PowerShell

Use the MSAL.PS library to acquire access tokens with Delegated permissions. Run the following commands to get access token on behalf of a user:

Install-Module -Name MSAL.PS # Install the MSAL.PS module from PowerShell Gallery

$TenantId = " " # Paste your directory (tenant) ID here.
$AppClientId="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # Paste your application (client) ID here.

$MsalParams = @{
   ClientId = $AppClientId
   TenantId = $TenantId
   Scopes   = 'https://graph.microsoft.com/User.Read.All','https://graph.microsoft.com/Files.ReadWrite','https://api.securitycenter.windows.com/AdvancedQuery.Read'
}

$MsalResponse = Get-MsalToken @MsalParams
$AccessToken  = $MsalResponse.AccessToken
 
$AccessToken # Display the token in PS console

Validate the token

  1. Copy and paste the token into JWT to decode it.
  2. Make sure that the roles claim within the decoded token contains the desired permissions.

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:

:::image type="content" source="/defender/media/defender-endpoint/webapp-decoded-token.png" alt-text="The permissions section in the Decoded Token pane in the Microsoft Defender portal" lightbox="/defender/media/defender-endpoint/webapp-decoded-token.png":::

Use the token to access the Microsoft Defender XDR API

  1. Choose the API you want to use (incidents, or advanced hunting). For more information, see Supported Microsoft Defender XDR APIs.
  2. 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. The token will expire within one hour. You can send more than one request during this time with the same token.

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();

Related articles